Automate Freight & Logistics Contracts via API: Rate Confirmations & BOLs (2026)

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json());

const SIGNBEE_API_KEY = process.env.SIGNBEE_API_KEY!;
const WEBHOOK_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET!;

interface LoadDispatchData {
  loadId: string;
  carrierName: string;
  carrierMc: string;
  driverName: string;
  driverPhone: string;
  driverEmail: string;
  origin: string;
  destination: string;
  pickupTime: string;
  lineHaulRate: number;
  fuelSurcharge: number;
  equipmentType: string;
}

// 1. Generate Markdown Rate Confirmation from TMS Load Data
function buildRateConMarkdown(load: LoadDispatchData): string {
  const totalPay = load.lineHaulRate + load.fuelSurcharge;
  return `# RATE CONFIRMATION & FREIGHT DISPATCH CONTRACT

**Load ID:** ${load.loadId}
**Date:** ${new Date().toISOString().split("T")[0]}

## 1. Carrier & Driver Information
- **Carrier Legal Name:** ${load.carrierName}
- **MC / DOT Number:** ${load.carrierMc}
- **Assigned Driver:** ${load.driverName}
- **Driver Contact:** ${load.driverPhone}
- **Equipment Specified:** ${load.equipmentType}

## 2. Route & Transit Schedule
- **Origin Loading Facility:** ${load.origin}
- **Scheduled Pickup Window:** ${load.pickupTime}
- **Destination Delivery Facility:** ${load.destination}

## 3. Financial Agreement & Accessorial Rates
| Component | Amount (USD) |
| :--- | :--- |
| Line-Haul Rate | $${load.lineHaulRate.toFixed(2)} |
| Fuel Surcharge (FSC) | $${load.fuelSurcharge.toFixed(2)} |
| **Total Agreed Rate** | **$${totalPay.toFixed(2)}** |

### Accessorial Terms & Detention Rules
1. **Free Time:** 2 hours free time at pickup and delivery.
2. **Detention Rate:** $75.00/hour thereafter, requiring real-time GPS check-in logs.
3. **Double Brokering Ban:** Re-brokering this load voids payment and incurs a $5,000 penalty fee under FMCSA broker rules.

By signing below, Carrier agrees to transport the described load under these explicit terms.`;
}

// 2. Endpoint: Dispatch Rate Con to Carrier Driver
app.post("/api/tms/dispatch-load", async (req, res) => {
  try {
    const loadData: LoadDispatchData = req.body;
    const markdownContract = buildRateConMarkdown(loadData);

    const apiResponse = await fetch("https://signb.ee/api/v1/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${SIGNBEE_API_KEY}`,
      },
      body: JSON.stringify({
        markdown: markdownContract,
        recipient_name: loadData.driverName,
        recipient_email: loadData.driverEmail,
        metadata: {
          load_id: loadData.loadId,
          carrier_mc: loadData.carrierMc,
          dispatch_type: "RATE_CONFIRMATION",
        },
        expires_in_days: 1,
      }),
    });

    if (!apiResponse.ok) {
      throw new Error(`Signbee API returned status ${apiResponse.status}`);
    }

    const { document_id, signing_url } = await apiResponse.json();

    // Trigger automated SMS to Driver (via Twilio or internal SMS gateway)
    // await sendSms(loadData.driverPhone, `Sign Rate Con for Load ${loadData.loadId}: ${signing_url}`);

    res.status(200).json({
      success: true,
      loadId: loadData.loadId,
      documentId: document_id,
      signingUrl: signing_url,
    });
  } catch (error: any) {
    res.status(500).json({ error: error.message });
  }
});

// 3. Webhook Listener: Process Completed Signatures Real-Time
app.post("/webhooks/signbee-complete", (req, res) => {
  const signature = req.headers["x-signbee-signature"] as string;
  const hmac = crypto.createHmac("sha256", WEBHOOK_SECRET);
  const digest = hmac.update(JSON.stringify(req.body)).digest("hex");

  if (signature !== digest) {
    return res.status(401).send("Invalid webhook signature HMAC");
  }

  const { event, data } = req.body;

  if (event === "document.signed") {
    const loadId = data.metadata.load_id;
    const pdfDownloadUrl = data.certified_pdf_url;
    const signedAt = data.completed_at;

    console.log(`[TMS UPDATE] Load ${loadId} signed by carrier at ${signedAt}.`);
    // Update TMS Database Status to DISPATCHED_LOCKED and store PDF URL
    // await tmsDb.loads.update({ where: { id: loadId }, data: { status: "DISPATCHED", rateConPdf: pdfDownloadUrl } });
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log("TMS Dispatch Server running on port 3000"));

import hmac
import hashlib
import json
import os
import requests
from fastapi import FastAPI, Request, HTTPException, Header

app = FastAPI(title="Logistics eBOL Automation Engine")

SIGNBEE_API_KEY = os.getenv("SIGNBEE_API_KEY", "sb_live_secret_key")
WEBHOOK_SECRET = os.getenv("SIGNBEE_WEBHOOK_SECRET", "whsec_logistics_secret")

def render_ebol_markdown(bol_data: dict) -> str:
    """Renders FMCSA-compliant eBOL markdown payload."""
    return f"""# ELECTRONIC BILL OF LADING (eBOL)
**eBOL Reference Number:** {bol_data['bol_number']}
**Date of Issuance:** {bol_data['ship_date']}

## 1. Shipping & Receiving Facilities
- **Consignor (Shipper):** {bol_data['shipper_name']}, {bol_data['shipper_address']}
- **Consignee (Receiver):** {bol_data['consignee_name']}, {bol_data['consignee_address']}
- **Carrier Name:** {bol_data['carrier_name']} (USDOT #{bol_data['usdot_num']})
- **Trailer / Container Number:** {bol_data['trailer_num']}

## 2. Commodity & Cargo Specification
| Item | Handling Units | Package Type | Weight (lbs) | Hazmat |
| :--- | :--- | :--- | :--- | :--- |
| {bol_data['commodity']} | {bol_data['pallets']} | Pallets | {bol_data['weight_lbs']} | NO |

## 3. Shipper Certification & Carrier Receipt
RECEIVED, subject to individually determined rates or contracts, the property described above in apparent good order.

*Shipper Signature (Pre-Signed at Gate):* {bol_data['shipper_name']}

*Driver Signature Required Upon Dock Departure below:*
"""

@app.post("/api/v1/ebol/create")
async def create_and_dispatch_ebol(payload: dict):
    bol_markdown = render_ebol_markdown(payload)
    
    headers = {
        "Authorization": f"Bearer {SIGNBEE_API_KEY}",
        "Content-Type": "application/json"
    }
    
    body = {
        "markdown": bol_markdown,
        "recipient_name": payload["driver_name"],
        "recipient_email": payload["driver_email"],
        "metadata": {
            "bol_number": payload["bol_number"],
            "load_id": payload["load_id"],
            "doc_type": "ELECTRONIC_BOL"
        },
        "expires_in_days": 2
    }
    
    response = requests.post("https://signb.ee/api/v1/send", headers=headers, json=body)
    if response.status_code != 200:
        raise HTTPException(status_code=500, detail=f"Signbee API error: {response.text}")
        
    res_data = response.json()
    return {
        "status": "DISPATCHED",
        "bol_number": payload["bol_number"],
        "document_id": res_data.get("document_id"),
        "signing_url": res_data.get("signing_url")
    }

@app.post("/webhooks/ebol-status")
async def handle_ebol_webhook(request: Request, x_signbee_signature: str = Header(None)):
    raw_body = await request.body()
    
    # Compute HMAC SHA-256 verification signature
    expected_sig = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    
    if not x_signbee_signature or not hmac.compare_digest(expected_sig, x_signbee_signature):
        raise HTTPException(status_code=401, detail="Invalid HMAC signature")
        
    event_data = json.loads(raw_body.decode('utf-8'))
    
    if event_data.get("event") == "document.signed":
        doc_meta = event_data["data"]["metadata"]
        certified_pdf = event_data["data"]["certified_pdf_url"]
        print(f"eBOL {doc_meta['bol_number']} signed! Certified PDF: {certified_pdf}")
        # Execute internal warehouse dispatch release workflow...
        
    return {"status": "SUCCESS"}