Virtual Seller Account

Teapplix API have special endpoints for selected partners. They are used to provide concept of virtual seller accounts, and are based on 3 main terms:

  • VSAccount API method - this is used to create, list or delete virtual seller accounts
  • VSObtainToken API method
    • Launch URL - this is an url that is returned as part of ObtainToken, that allow you to optionally launch an embedded Teapplix UI screen
  • VSChannel API method - this is used to list the channels that a particular virtual seller has linked.

Note that this section of the API are only turned on for accounts with special setup that allow virtual sellers to be defined. For all other accounts if you attempt to call these API you will get an error return.

VSAccount

This method allows partners to perform the following operations

  • POST - create new "virtual seller account". Virtual seller is not same as separate Teapplix account. All virtual users are stored in the same master Teapplix account that the partner owns and operates
  • GET - list existing virtual seller accounts
  • DELETE - delete a particular virtual seller account. Once deleted, all the linked marketplace that the virtual seller created in Teapplix will also be deleted and sync will no longer happen.

Request/response details for this method:

VSObtainToken

From partner system, you will call this API to obtain the parameters needed to open a Teapplix embedded window inside your application:

Request to this method is done via HTTP GET:
https://api.teapplix.com/api2/VSObtainToken?VSAccountID=XYZ,

When it's required to allow virtual seller to interact with Teapplix UI, partner system should do next:

  1. Call VSObtainToken
  2. Redirect browser to launch URL: https://app.teapplix.com/h/AccountName/te/lo.cgi?Action=Launch&access_token=AccessToken&ts=unixtimestamp&account_id=XYZ&signature=signedstringvalue.
  3. Check next section for samples how to calculate signature=signedstringvalue
  4. Note, that issued temporary access token will expire in 30 minutes, if not used

Please, not that this method is protected and you need to specify APIToken HTTP-header in request, as well as for any other protected API method.

Request/Response details:

Launch URL

Launch URL is used as start point for UI in cases when "virtual user" need to visit Teapplix UI.
This URL makes authentication, so that there is not need to enter login/password values and user can "jump" directly to his UI.
UI will allow to interact with only theirs data, as well as add token and integrations to marketplaces.

Base host is: https://app.teapplix.com/
URI and options are next:

Base URI: /h/AccountName/te/lo.cgi

  • AccountName

AccountName is your Teapplix account name

  • Action=Launch

Constant

  • access_token=AccessToken

Result of ObtainAccessToken API method call

  • ts=unixtimestamp

unixtimestamp is integer value of UNIX epoch, for example: 1483257600

  • account_id=XYZ

account_id is id of "virtual user". 3 symbols.

  • signature=signedstringvalue

Signature Key

  • Signature Key

Signature key is the key generated or assgined on your Account API page.

More details about

Partner should calculate this URL and do redirect with HTTP Location and code 302 to it.

  • Signature

Signature is parameter which is sent in "launch URL". It should be calculated based on next scheme:
hmac(sha256(uri), Signature Key).asHexValue().

"URI" is full uri with options (for example: /h/demo2/te/lo.cgi?Action=Launch&access_token=AccessToken&ts=unixtimestamp&account_id=XYZ), and Signature Key is the key generated or assgined on your Account API page.
After signature was calculated, result value should be added to uri and result URI is address which user's browser should be redirected to.

/h/demo2/te/lo.cgi?Action=Launch&access_token=AccessToken&ts=unixtimestamp&account_id=XYZ&signature=a19fe6204cb34767f48260719c4f25a9ae5e966e8

Samples of implementation:

  • Perl
use Digest::SHA qw(hmac_sha256_hex);
my $options = '/h/demo2/te/lo.cgi?Action=Launch&access_token=AccessToken&ts=unixtimestamp&account_id=XYZ';
my $signature = hmac_sha256_hex($options, 'Signature Key');
my $url = $options . '&signature=' . $signature;
  • PHP
$options = '/h/demo2/te/lo.cgi?Action=Launch&access_token=AccessToken&ts=unixtimestamp&account_id=XYZ';
$signature = hash_hmac('sha256', $options, 'Signature Key', false);
$signedURL = $options . '&signature=' . $signature;
  • Python
  import hmac
  import hashlib

  options = '/h/demo2/te/lo.cgi?Action=Launch&access_token=AccessToken&ts=unixtimestamp&account_id=XYZ';
  signature = hmac.new(str('Signature Key'), options, hashlib.sha256).hexdigest()
  url = options . '&signature=' . signature;