Postman

During the development of fulfillmenttools as an API-first product, the design, documentation, and testing of the APIs are a high priority. Therefore, a comprehensive Postman collection is used and frequently updated with new requests as they appear in the API.

This page shares this resource with developers or other technical personnel to simplify access to the fulfillmenttools REST API and share concrete examples.

Available resources

Postman functionality includes collections, environments, and mock servers. For documentation purposes, fulfillmenttools provides a template environment and the collection of calls to the fulfillmenttools REST API. To work with the collection, import the environment into Postman and populate the data as described below.

Step 1: Import or create fulfillmenttools environments in Postman

The environments contain variables that tell Postman where to address specific calls and which data should be used. To test an existing fulfillmenttools system using the Postman collection, importing and setting up environments is recommended.

To review the calls without executing them, setting up an environment is not required.

Two environments are necessary to work with Postman: one global and one tenant-specific. To create the global one, download the Globals environment template and import it. Refer to the Postman documentation on how to import data.

Perform the same step for the tenant-specific environment. An example file is available for download. Remember to replace the example ocff-example-prd with the correct projectId.

While projectId and host can be added to one environment, separating them is helpful if additional tenant environments are added.

The tenant-specific environment has to contain the projectId:

Variable	Description	Example Value
projectId	The ID of the project being used.	ocff-example-prd

The global environment must contain the host value:

Variable	Description	Example Value
host	The host of the fulfillmenttools platform environment. The {projectId} variable is automatically substituted from the tenant-specific environment.	https://{projectId}.api.fulfillmenttools.com/

When using Postman, more variables will appear in the environment. Note that authTokens and refreshTokens will be stored in the environment of the local Postman instance.

Step 2: Import the fulfillmenttools API collection into Postman

Similar to an environment, the collection can be imported into Postman. Download the collection file and import it as described in the Postman documentation on importing data.

The fulfillmenttools API and this collection are regularly updated. It is recommended to periodically update the local collection to get the latest changes.

After successfully importing the collection, a view similar to this appears:

List of fulfillmenttools products and their respective REST calls

Step 3: Define authentication Postman Vault values

The Postman Vault is used to prevent syncing sensitive data to the Postman Cloud. It provides local, encrypted storage that is not synchronized. Access the Postman Vault via the Vault button in the bottom right corner of the Postman interface.

Set the following variables in the vault. In the variable names, replace {projectId} with the project ID (e.g., ocff-example-prd-user for the project ocff-example-prd).

Variable	Description	Example Value
{projectId}-user	The user that exists in the system, usually in the form of an email. Include the host part of the login.	[email protected]
{projectId}-password	The password of the user.
{projectId}-api-key	The API key for the identity provider, used to generate an authentication token.	AIZaSyCvIDK187vJWfl5EICJ_g_bNyvdARhdeXw

Postman may encounter issues if the password contains quotation marks or a backslash. In this case, escape the character by prepending it with a backslash.

Example: My"Nice\Password becomes My\"Nice\\Password

Step 4: Make an API call using Postman

First, get an authentication token. This token is then used in calls to the fulfillmenttools API.

Requesting a new authentication token using environment variables.

After a successful call, the identity provider returns a response containing the authToken and refreshToken. Both values are automatically stored as environment variables.

With a valid token, any call in the collection can be executed. For example, to request the list of facilities:

The result of the request to get all facilities