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.
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:
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:
When it's required to allow virtual seller to interact with Teapplix UI, partner system should do next:
- Call VSObtainToken
- 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.
- Check next section for samples how to calculate signature=signedstringvalue
- 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.
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 is your Teapplix account name
Result of ObtainAccessToken API method call
unixtimestamp is integer value of UNIX epoch, for example: 1483257600
account_id is id of "virtual user". 3 symbols.
- 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 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.
Samples of implementation:
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;
$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;
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;