BOL images and Delivery Ticket Download

Overview

The following document summarizes a workflow to authenticate, get orders, download bol images and download delivery tickets from the Supply and Dispatch API.

To access our official API documentation please navigate to: https://docs.gravitate.energy/docs/api/index.html

Pre-requisites

Upon understanding the workflow, a consultant will set up a client ID and a client secret for you. Please store both of these values securely.

• Client ID
• Client Secret

Step 1: Authenticating with the API:

To refer to the official documentation please navigate to:

https://docs.gravitate.energy/docs/api/supply-dispatch-public-api

To acquire a token from our API, you must provide the following parameters in your request:

• Client ID
• Client Secret

Example python implementation:

Parameters

Name	Type	Description
client_id	String	The client_id for authentication.
client_secret	String	The client_secret for authentication.
scope	String	The scope of the access token (e.g., "bbd").

Request

• HTTP Method: POST
• URL: {base_url}/v1/token

Response

• Success Response (200 OK)

  jsonCopy code
  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    // Other JWT claims...
  }
  • access_token (String): The access token (JWT) issued upon successful authentication.
  • Error Response
    • 401 Unauthorized: If the provided credentials are invalid or if the user is not authorized.

Example python implementation:

def get_token(client_id:str, client_secret:str, scope:str = 'bbd') -> str | None:
        r = requests.post(
            f"{self.url}/api/token",
            data={
                "client_id": client_id,
                "client_secret": client_secret,
                "scope": scope,
            },
        )

        if r.ok:
            return r.json()["access_token"]

				except requests.exceptions.HTTPError as http_err:
            logging.error(f"HTTP error occurred: {http_err}")
        except Exception as err:
            logging.error(f"An error occurred: {err}")

        return None

Step 2: Retrieving new complete orders :

To refer to the official documentation please navigate to:

https://docs.gravitate.energy/docs/api/supply-dispatch-public-api

Request Parameters

The request should be a JSON object containing the following fields:

Request Object

Field Name	Type	Description
order_id	string	An optional string identifier for a specific order.
order_number	int	An optional integer identifier for a specific order.
type *****	string	An optional string specifying the type of order.
state ******	string	An optional string indicating the state of the order (e.g., 'deleted').
last_change_date	string	An optional string representing the last change date in ISO 8601 format.

Note: At least one of the above fields must be included in the request.

*Available order types: carrier_adhoc, carrier_inventory_managed (To be updated in official documentation)

**Available order states: deleted', 'unset', 'open', 'recommended', 'accepted', 'assigned', 'in progress' or 'complete'

Example Request

POST {base_url}/v1/get_orders
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "order_number": 145789,
  "last_changed_date": "2024-05-29T14:26:50.930Z",
}

import requests
import json

url = f"https://{base_url}/v1/order/get_orders"

payload = json.dumps({
  "order_id": "string",
  "order_number": 0,
  "type": "string",
  "state": "complete",
  "last_change_date": "2024-05-29T14:26:50.930Z"
})
# Must retrieve access token before. Use Step 1 to do so
token = get_token(...)
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': f'Bearer {token}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Step 3: Retrieve bol images and delivery tickets

Once the list of new completed orders has been retrieved, it can be used to retrieve the corresponding bol images and delivery tickets.

3.1 Retrieve BOL images:

To refer to the official documentation please navigate to:

https://docs.gravitate.energy/docs/api/supply-dispatch-public-api

Request Parameters

The request should be a JSON object containing the following fields:

Request Object

Field Name	Type	Description
order_ids	list[string]	A list of unique identifiers for orders. Can be left empty if order_numbers is provided.
order_numbers	list[string]	A list of order numbers. Can be left empty if order_ids is provided.

Providing both order_ids and order_numbers will extend the search to include all specified identifiers.

Example Request

POST {base_url}/v1/bol_image
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "order_numbers": ['15546','15547']
}

Example python implementation:

import requests
import json

url = f"https://{base_url}/v1/bol_images"
# Must retrieve order numbers and order ids before. Use Step 2 to do so 
order_ids = get_order_ids(...)
order_numbers = get_order_numbers(...)
payload = json.dumps({
  "order_ids": order_ids,
  "order_numbers": order_numbers
})
# Must retrieve access token first. Use Step 1 to do so
token = get_token(...)
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': f'Bearer {token}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

3.2 Retrieve delivery tickets

To refer to the official documentation please navigate to:

https://docs.gravitate.energy/docs/api/supply-dispatch-public-api

Request Parameters

The request should be a JSON object containing some of the following fields:

Request Object

Field Name	Type	Description
order_id	string	A unique identifier for an Order. Can be left empty if order_number is provided.
order_number	int	A number to identify an Order. Can be left empty if order_id is provided.
site_id	string	A unique identifier for a Site. Can be left empty if site_number is provided.
site_number	string	A number to identify a Site. Can be left empty if site_id is provided.

Request must include both (site_id and order_id ) or ( site_number and order_number****)

POST {base_url}/v1/delivery_ticket
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "order_number": 145789,
  "site_number": "23",
}

Example python implementation:

import requests
import json

url = f"https://{base_url}/v1/delivery_ticket"
# Must retrieve ordes
orders = get_orders(...)
token = get_token(...)
# For each order, get the order_id and site_id
for order in orders:
	# Access drop information
	drops = order ['drops']
	order_id = order['order_id']
	site_id = drops.get('location_id')

	payload = json.dumps({
	  "order_id": order_id,
	  "site_id": order_numbers
	})
# Must retrieve access token first. Use Step 1 to do so

	headers = {
	  'Content-Type': 'application/json',
	  'Accept': 'application/json',
	  'Authorization': f'Bearer {token}'
	}
	
	response = requests.request("POST", url, headers=headers, data=payload)

	print(response.text)