Authentication

Omisell API use token based as its authentication mechanism

1.Get API Key

1.1 For Seller Integration

Before you can start using our APIs, you need an API key. It's easy. Just login to https://app.omisell.com and next step go to API Intergrated API Tool to create API key.

Once you've activated your key, you're ready to roll.

1.2 For a Omisell's Partner Integration

To be provided with a Partner Key, you need to demonstrate that you are a service provider for multiple sellers and that you are authorized by your clients to manage their data through the platform.

You need to contact us to be provided with a Partner Key.

💡 Please keep your API KEY in a secret and secure manner. DO NOT store them in publicly accessible places like GitHub, client-side code and so on.
💡 All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

2. Get Access Token

Domain API: https://api.omisell.com

Step 1: Send HTTP Request

The above command returns JSON structured like this:

{
    "data": {
      "expired_time": 1703578845,
      "refresh_expired_time": 1704788445,
      "refresh_token": "xxxxx",
      "token": "xxxxxxxx"
  },
    "error": false,
    "error_code": 201,
    "attr_error": null,
    "messages": ""
}

Step2: Add data to header

 Authorization : 'Omi ' + token
 Content-Type : 'application/json'

Or Account key if you are using multiple business.

Authorization : 'Account ' + account_key
Content-Type : 'application/json'

Or Partner key if you are partner of Omisell.

Authorization : 'Partner ' + partner_key
Seller-ID : 'xxxxx'
Country : 'xxxxx'
Content-Type : 'application/json'

3. Refresh Token

Once an app is authorized by a seller account, it obtains an access token, which is essential for authenticating and making calls to Omisell's APIs.

However, this access token needs to be refreshed every days using a refresh_token. Failure to refresh the access_token before its expiration will result in authentication failure when attempting to request data through the API.

The access token remains valid until the refresh_expire_date, which is returned in the response.

Send HTTP Request

The above command returns JSON structured like this:

{
    "data": {
      "expired_time": 1703578845,
      "refresh_expired_time": 1704788445,
      "refresh_token": "xxxxx",
      "token": "xxxxxxxx"
  },
    "error": false,
    "error_code": 201,
    "attr_error": null,
    "messages": ""
}

Or Merchant token if your integration was connected through Omisell's merchant-connect flow.

 Authorization : 'Merchant ' + token
 Shop-ID : 'xxxxx'
 Content-Type : 'application/json'

💡 Which scheme you get depends on how you were onboarded. Merchant is issued by the merchant-connect flow and is the ONLY scheme accepted by POST /order/info-buyer and GET /order/by-buyer/{buyer_id}; Partner is the only scheme accepted by GET /seller-by-partner/list. Every other endpoint on this site accepts Omi, Account, Partner and Merchant.

WARNING

Ngoài 4 scheme trên, backend còn bật HMACAuthentication (header Key / Signature / Timestamp, có kiểm lệch giờ) và BasicAuthentication ở cấu hình mặc định. Thông báo 403 của hệ thống có chỗ hướng dẫn dùng HMAC api_key, nhưng cách ký chưa được mô tả ở đâu trong tài liệu này — liên hệ Omisell nếu bạn được cấp HMAC key.

Access token sống 1 ngày, refresh token 15 ngày (refresh_expired_time trong response là mốc chính xác). Hạn của token còn bị cắt theo hạn của API key sinh ra nó.

1.Get API Key#

1.1 For Seller Integration#

1.2 For a Omisell's Partner Integration#

2. Get Access Token#

Step 1: Send HTTP Request#

Step2: Add data to header#

3. Refresh Token#

Send HTTP Request#