Table of Contents

So far, the Swagger and Postman aren’t linked. The example you’ll see will not apply the updates done on one side to the other side.

Swagger Import

To import your files on postman, you just have to click on the import button and choose your file. This will create an API, Collection and a Documentation object.

You can keep the default settings or change it during the import

Configuration

To use Postman with consistent data, you’ll have to set up some variables.

Environment variables

The environment variables will help you reproduce the environment you want to use (development, staging, prod …). To initialise a new environment, you just have to click on the new button and choose Environment and set it to the active environment :

You can create as many environments as you want and switch between them.

API keys

First of all, you’ll need API keys. There are 3 types : guest, ambassador and brand API keys

The guest API key is initialized in the global.php file, associated to the key POPSELL_API_GUEST_KEY. For the V4, it will be used only at the first call of the API/v4/auth to load the Brand and the BrandTheme. This access is the most restricted.

The brand API key is used once the Brand is loaded. It will be used to access to almost all the informations of the brand and its content (like ambassadors ans their informations, posts, gamifications, chat messages and members, E-learning …). The brand API key is set with an API Marque type in the Configuration/API in the Back Office.

The ambassador API key is used when a connected ambassador wants to access to its own information (like personal informations, gamification, contacts …) or to limited information he has been granted access (like members list or map, blogs and shops, posts, personal or group chat messages …). To fetch an ambassador API key, you have to use the brand API key initialised above and call the /ambassadors/{ambassador_id} route that return all the targeted ambassador informations including its api_key.

A brand can't access another brand information.

Callback url

If needed, you can also fill your callback url set in the Configuration/API in your Back Office

Url

You may also want to set your own API uri. This URI will be composed of your brand URL (e.g.: https://brand.user.popdev.popsell.com for dev envs or https://brand.com for prod envs) followed by /api/v4

To initialise your environment variables, you just have to create a new variable and link it to it’s value.

Referer

You will need a referer variables for the /auth routes. It is used to identify the brand on which you are working. You just have to set it with a http://[domain] structure.

Environment variables list

Here is the list of the variables needed for a proper use of your environment :

  • guest_api_key

  • ambassador_api_key

  • brand_api_key

  • baseApiUri

  • (Optional) callbackUrl

  • referer

Collection variables

The collection variables contains variables you will use multiple times in your API requests. It can be an object identifier or a query parameter.

To modify it, you just have to access to your collection then you will go in variables section in which you can initialize your variables.

Collection variables list

We recommend you to use the collection variables. It will allow you to change easily the object targeted or the query parameter you are using for the whole API instead of changing it for each route and to deploy quickly and easily the API.

Here is a list of which variables are used :

  • post_id
    Preferred a post with products, comments, likes etc

  • comment_id
    Preferred a post linked comment id

  • ambassador_id
    Represents the connected ambassador

  • on_boarding_id
    Used to trigger an onboarding sequence. You have to create one in your B.O to use this variable

  • contact_id
    Used to optin and optout contact

  • id_tutorial_category

  • id_tutorial

  • id_ambassador_meeting
    Used for add and remove participation to an event

  • id_brand_tag
    Brand tag visible by ambassadors both on Instant Messaging groups and on community

  • contact_category_id
    Categories assigned to the ambassadors contacts

  • register_id
    Customer identifier or webservice identifier or email

  • challenge_id
    Challenge that the connected ambassador is allowed to access or view

  • point_of_sale_id

  • product_category_id

  • product_id

  • quiz_id

  • quiz_answer_id
    Must match an answer from the quiz above

  • favorite_id
    Can be a post, a group or a group chatroom (more than 2 users) id

Be careful, some IDs are used to delete data

API

Usage

Authentication

For now, we can’t set a default value to the bearer tokens. Therefore you have to set the bearer tokens for each routes. You can as desired :

  • Set the authentication token filled in routes descriptions

  • Inherit from parent. This way the route have the same bearer token as the parent folder.