Flow Execution Integration Guide

Suggest Edits

This document provides instructions for integrating your shipment data with our flow execution API. This integration enables Digital Genius to apply proactive business logic and automate customer communications, such as notifying customers of order delays or providing shipment updates through your customer service channels.

Overview

The Flow Execution API allows you to send shipment data to a specified Digital Genius flow, which then applies business rules and triggers automated customer communications. For example, when a shipment is delayed, the system can proactively notify affected customers through their preferred channel.

Authentication

The API uses Basic Authentication with your API key and secret.

Credentials:

API Key: To be provided by the Digital Genius implementation team
API Secret: To be provided by the Digital Genius implementation team
Region: eu (European region) or us(American Region)
Flow ID: To be provided by the Digital Genius implementation team based on your specific use case

API Endpoint

https://flow-server.{region}.dgdeepai.com/execution

Integration Steps

1. Generate Authentication Token

Create a Base64-encoded token by combining your API key and secret:

API_KEY:API_SECRET → Base64 encoded

2. Create Request Headers

Authorization: Basic {your_base64_token}
Content-Type: application/json

3. Prepare Payload

Structure your payload as follows (example only)

{
  "action_id": "{flow_id}",
  "external_id": "{your_unique_request_id}",
  "inputs": {
    "external_id": "{your_unique_request_id}",
    "shipment_data": {
      "order_id": "123",
      "shipment_id": "SHIP123456",
      "tracking_number": "RM123456789GB",
      "carrier_code": "royalmail",
      "items": [
        {
          "sku": "PROD123",
          "quantity": 1
        }
      ]
    }
  }
}

Notes:

action_id: The flow ID provided to you by the Digital Genius implementation team
external_id: A unique identifier for this request (can be your shipment ID or order ID with a timestamp)

4. Send the Request

Make a POST request to the execution endpoint with your headers and payload.

Example Request (Curl)

#!/bin/bash

# Configuration variables
DG_API_KEY="your_api_key"  # Provided by Digital Genius
DG_API_SECRET="your_api_secret"  # Provided by Digital Genius
REGION="eu"
FLOW_ID="your_flow_id"  # Provided by Digital Genius
EXTERNAL_ID="SHIPMENT_REQ_$(date +%s)"  # Unique ID using timestamp (example)

# Generate the authentication token
DG_TOKEN=$(echo -n "${DG_API_KEY}:${DG_API_SECRET}" | base64)

# Create the payload with shipment data
PAYLOAD='{
  "action_id": "'"${FLOW_ID}"'",
  "external_id": "'"${EXTERNAL_ID}"'",
  "inputs": {
    "external_id": "'"${EXTERNAL_ID}"'",
    "shipment_data": {
      "order_id": "123",
      "shipment_id": "SHIP123456",
      "tracking_number": "RM123456789GB",
      "carrier_code": "royalmail",
      "items": [
        {
          "sku": "PROD123",
          "quantity": 1
        }
      ]
    }
  }
}'

# Make the API request using curl
curl -X POST \
  "https://flow-server.${REGION}.dgdeepai.com/execution" \
  -H "Authorization: Basic ${DG_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "${PAYLOAD}"

Example in Python

import json
import requests
from base64 import b64encode
from datetime import datetime

# Configuration
api_key = "your_api_key"  # Provided by Digital Genius
api_secret = "your_api_secret"  # Provided by Digital Genius
region = "eu"
flow_id = "your_flow_id"  # Provided by Digital Genius
external_id = f"SHIPMENT_REQ_{int(datetime.now().timestamp())}"

# Generate authentication token
auth_token = b64encode(f"{api_key}:{api_secret}".encode("utf-8")).decode("ascii")

# Set headers
headers = {
    "Authorization": f"Basic {auth_token}",
    "Content-Type": "application/json"
}

# Prepare payload
payload = {
    "action_id": flow_id,
    "external_id": external_id,
    "inputs": {
        "external_id": external_id,
        "shipment_data": {
            "order_id": "123",
            "shipment_id": "SHIP123456",
            "tracking_number": "RM123456789GB",
            "carrier_code": "royalmail",
            "items": [
                {
                    "sku": "PROD123",
                    "quantity": 1
                }
            ]
        }
    }
}

# Send request
response = requests.post(
    f"https://flow-server.{region}.dgdeepai.com/execution",
    headers=headers,
    json=payload
)

# Handle response
print(f"Status Code: {response.status_code}")
print(response.json() if response.ok else response.text)

Shipment Data Fields

Field	Description	Required	Example
order_id	Your internal order ID	Yes	"123456"
shipment_id	Your internal shipment ID	Yes	"SHIP123456"
tracking_number	The carrier tracking number	Yes	"RM123456789GB"
carrier_code	The code for the shipping carrier	Yes	"royalmail"
items	Array of items in the shipment	Yes	See below

Item Fields

Field	Description	Required	Example
sku	Product SKU	Yes	"PROD123"
quantity	Number of items	Yes	1

Use Cases

This integration enables several proactive customer service scenarios, including:

Shipment Delay Notifications: Automatically inform customers when their order is delayed
Out-of-Stock Alerts: Notify customers when an item in their order is unavailable
Delivery Confirmations: Send confirmation messages when an order has been delivered
Return Processing Updates: Keep customers informed about the status of their returns

Updated 3 days ago