Skip to main content

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​

NameTypeDescription
client_idStringThe client_id for authentication.
client_secretStringThe client_secret for authentication.
scopeStringThe 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 NameTypeDescription
order_idstringAn optional string identifier for a specific order.
order_numberintAn optional integer identifier for a specific order.
type *****stringAn optional string specifying the type of order.
state ******stringAn optional string indicating the state of the order (e.g., 'deleted').
last_change_datestringAn 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 NameTypeDescription
order_idslist[string]A list of unique identifiers for orders. Can be left empty if order_numbers is provided.
order_numberslist[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 NameTypeDescription
order_idstringA unique identifier for an Order. Can be left empty if order_number is provided.
order_numberintA number to identify an Order. Can be left empty if order_id is provided.
site_idstringA unique identifier for a Site. Can be left empty if site_number is provided.
site_numberstringA 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)