Access to fulfillmenttools APIs

There are multiple methods to make API calls with fulfillmenttools. In this article, we'll take you through making your first API calls with Postman, cURL, and GraphQL.

If you're on a free trial, we suggest following our free trial guides.

Prerequisites

• fulfillmenttools tenant and login credentials

If you don't have access to a tenant, you'll need to ask the Administrator in your team to invite you. Once invited, you'll have access to the information below that you'll need to work with our APIs:

• API URL of your tenant

• API key (also referred to as AUTHKEY)

• Username

• Password

Postman

A comprehensive Postman collection is used and frequently updated with new requests as they appear in the API. To work with the collection, follow the steps below:

1

Import the fulfillmenttools collection to Postman

Download the raw GitHub file and add it to the collection section of Postman.

This collection are regularly updated. It's recommended to periodically update the local collection to get the latest changes.

2

Create an environment

Go to the environment section and create a new environment. Add the below to your new environment. Your projectId is your tenant name and can be found in the email you received from us, which will resemble ocff-{uniqueID}-pre.

Variable	Value
projectId	{the project ID in the email you received}
host	https://{projectId}.api.fulfillmenttools.com/

3

Add credentials to the Postman Vault

Go to the Postman Vault (bottom right of the Postman screen), and add the below to your Vault. You'll find all the values in the email you received from us (if you've changed the password in Backoffice, use that password instead of the one in the email).

Variable	Value
{projectId}-user	{the username in the email you received}
{projectId}-password	{the password in the email you received}
{projectId}-api-key	{the API key in the email you received}

We use the Postman Vault to store these sensitive variables to avoid syncing them to the Postman Cloud.

4

Make your first API call to get an Auth token

Go to the fulfillmenttools collection, select POST Request Auth Token, ensure your environment is selected, and click Send.

You should get a 200 response. If you go back to your environment settings, you'll see that an authToken and a refreshToken have been automatically created.

You'll need to run the POST Refresh Auth Token endpoint at least every 60 minutes.

You're now ready to use all the other calls in the Postman collection. 🎉

For example:

GET https://{projectId}.api.fulfillmenttools.com/api/facilities

cURL

cURL is one command line tool (CLI) you can use to do REST API calls. Here's an example of how it must be used for our platform.

1

Get an authentication token

Open your preferred CLI and use the below input.

You'll need to add your own AUTHKEY, email, and password.

cURL authorization request

curl -sSL -X POST 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={authKey}' \
--header 'content-Type: application/json' \
--data-raw '{
    "email": "{your-email-address}",
    "password": "{your-password}",
    "returnSecureToken": true
}'

Be sure to make note of both the idToken and refreshToken as you'll need both of these.

2

Make an API call

You're now ready to use all the other API calls using cURL. For example, the below will create a new facility. You'll need to replace {projectID} with your tenant name, and replace {idToken} with the authorization token from above.

You must send headers for Authorization and Content-Type. Also replace https://{projectId}.api.fulfillmenttools.com/api/facilities with your specific host and endpoint.

cURL create facility example

curl -sSL -X POST 'https://{projectId}.api.fulfillmenttools.com/api/facilities' \
--header 'Authorization: Bearer {idToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Nerd Herd Clothing",
  "address": {
    "companyName": "Nerd Herd Clothing",
    "country": "US",
    "postalCode": "81669",
    "city": "München",
    "street": "Lilienstr.",
    "houseNumber": "58"
  },
  "services": [
    {
      "type": "COLLECT"
    }
  ],
  "status": "ONLINE",
  "locationType": "STORE"
}'

You'll need to call the POST Refresh Auth Token endpoint at least every 60 minutes.

GraphQL Explorer

fulfillmenttools GraphiQL

The official fulfillmenttools playground, powered by GraphiQL, is hosted under https://{projectId}.graphql.fulfillmenttools.com/graphql. It enables interactive exploration of queries and documentation. Authentication tokens must be entered in the Headers tab at the bottom of the page.

Altair

For in-depth query development on the fulfillmenttools GraphQL API, we recommend Altair, available as a browser plugin and a standalone application. We also provide a pre-request script to automatically refresh authentication tokens, similar to our Postman collection.

To start with Altair, enter your tenant's GraphQL URL in the URL bar. Note that using Altair for schema introspection won't include schema directives and lifecycle information from generated GraphQL schemas.

Pre-request script for Altair

The following guide shows how to set up a pre-request script in Altair.

1

Create a new environment

First, create a new environment for your tenant:

Fill the following information in the environment:

{
  "user": "YOUR-USER-EMAIL",
  "password": "YOUR-PASSWORD",
  "host": "https://{projectId}.graphql.fulfillmenttools.com/graphql",
  "apiKey": "YOUR-API-KEY"
}

2

Add the Pre-request script

Click on the Pre-request tab and add the script below. Ensure you've checked the Enable pre-request script check box.

Pre-request script to copy

const lastTokenCall = await altair.storage.get("lastTokenCall");
const now = new Date();
if (!lastTokenCall || now - (new Date(lastTokenCall)) > 1800000) {
  altair.log("Refreshing token...");
  var user = altair.helpers.getEnvironment('user');
  var apiKey = altair.helpers.getEnvironment("apiKey");
  var escapedPwd = altair.helpers.getEnvironment('password');
  escapedPwd = escapedPwd.replace(/\\/g, '\\\\');
  escapedPwd = escapedPwd.replace(/\'/g, '\\\'');
  escapedPwd = escapedPwd.replace(/\"/g, '\\\"');
  escapedPwd = escapedPwd.replace(/\`/g, '\\\`');
  await altair.storage.set("lastTokenCall", new Date());
  const authUrl = 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=' + apiKey
  const authResult = await fetch(authUrl, {
        "method": "POST",
        "body": JSON.stringify({
          "email": user,
          "password": escapedPwd,
          "returnSecureToken": true
        })
  }).catch((e) => altair.log(e))
  const data = await authResult.json()
  altair.helpers.setEnvironment("authToken", data.idToken, true);
  altair.helpers.setEnvironment("refreshToken", data.refreshToken, true);
}

3

Adjust the Authentication header

Click the Set Headers icon in the left-hand navigation.

Then, adjust the authentication header to use the automatically generated token and click Done.

The script will automatically refresh the authentication token when it's older than 30 minutes.