Route optimisation

Integrating route optimisation

This section explains how to call the route optimisation group. The full endpoint list is directly below; what follows is what you need before the first call.

Submitting a job

Route optimisation runs asynchronously. You submit a job, the system accepts it and works on it, and you collect the result later by asking for the status or by receiving a webhook.

const idempotencyKey = crypto.randomUUID();

async function submit(body: unknown) {
  const response = await fetch(
    "https://<your-host>/api/v1/partners/addons/route-optimization/jobs",
    {
      method: "POST",
      headers: {
        "api-key": process.env.ROUTE4GREEN_API_KEY!,
        "Idempotency-Key": idempotencyKey,
        "content-type": "application/json",
      },
      body: JSON.stringify(body),
    },
  );

  // 202 Accepted. The job is recorded, not finished.
  const envelope = await response.json();
  if (!envelope.success) {
    throw new Error(`${envelope.error_code}: ${envelope.message}`);
  }
  return envelope.data;
}

Job lifecycle

A job moves through six states. These are the literal strings the system returns, so match on them exactly rather than translating them or changing their case.

This list comes from the backend team. The pinned specification does not publish the set, so if you see a state that is not here, tell us.

Polling for status

If you are not using webhooks, ask for the status on an interval and stop as soon as the job reaches one of the four terminal states. Always bound the loop: the current processing timeout is 30 minutes, so an unbounded loop runs forever when something goes wrong.

const TERMINAL = new Set([
  "SUCCEEDED",
  "PARTIAL",
  "FAILED",
  "CANCELLED",
]);

async function waitForJob(jobId: string, deadlineMs = 30 * 60 * 1000) {
  const startedAt = Date.now();

  while (Date.now() - startedAt < deadlineMs) {
    const response = await fetch(
      `https://<your-host>/api/v1/partners/addons/route-optimization/jobs/${jobId}`,
      { headers: { "api-key": process.env.ROUTE4GREEN_API_KEY! } },
    );
    const envelope = await response.json();
    if (!envelope.success) {
      throw new Error(String(envelope.error_code));
    }

    const status: string = envelope.data.status;
    if (TERMINAL.has(status)) return status;

    await new Promise((resolve) => setTimeout(resolve, 5_000));
  }

  throw new Error("Job did not reach a terminal state before the deadline");
}

Webhooks

Instead of asking repeatedly, register an address for the system to call when a job finishes. These are the route optimisation webhook endpoints, which are not the same feature as the general webhooks group elsewhere in this documentation.

Registering a webhook also needs an API key, and you cannot mint one yourself yet. See the authentication section on the documentation index.

import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.ROUTE4GREEN_WEBHOOK_SECRET!;

/**
 * HMAC-SHA256 over the four delivery parts joined by dots, in this order.
 * Anything else, including a different separator, produces a digest that
 * never matches.
 */
function expectedSignature(
  timestamp: string,
  eventId: string,
  eventType: string,
  rawBody: string,
): string {
  const preimage = `${timestamp}.${eventId}.${eventType}.${rawBody}`;
  return createHmac("sha256", SECRET).update(preimage).digest("hex");
}

function safeEqualHex(a: string, b: string): boolean {
  const left = Buffer.from(a, "hex");
  const right = Buffer.from(b, "hex");
  // Compare lengths first: timingSafeEqual throws on a mismatch.
  return left.length === right.length && timingSafeEqual(left, right);
}

export async function POST(request: Request): Promise<Response> {
  // Raw bytes, not a parsed object. Re-serialising JSON reorders keys and
  // every signature then fails.
  const rawBody = await request.text();

  const timestamp = request.headers.get("x-smartway-timestamp") ?? "";
  const eventId = request.headers.get("x-smartway-event-id") ?? "";
  const eventType = request.headers.get("x-smartway-event") ?? "";
  const received = (request.headers.get("x-smartway-signature") ?? "").replace(/^sha256=/, "");

  if (!timestamp || !eventId || !eventType || !received) {
    return new Response("missing signature headers", { status: 400 });
  }

  if (!safeEqualHex(received, expectedSignature(timestamp, eventId, eventType, rawBody))) {
    return new Response("invalid signature", { status: 401 });
  }

  // Your own freshness window. No server-side replay window is documented,
  // so choose one and reject anything older.
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > 300) {
    return new Response("stale delivery", { status: 401 });
  }

  // Deliveries can repeat, so key your handler on eventId and make it safe to
  // run twice. Acknowledge first: the delivery timeout is 5 seconds.
  void handleTerminalEvent(eventId, eventType, JSON.parse(rawBody));
  return new Response("ok");
}

Response envelope

Every response comes back in the same envelope: success, message, error_code and data. The important part is that the HTTP status is not always the signal. Some failures come back as HTTP 200 with success set to false. Always check the body, not only the status code.

// error_code is a string on some responses and a number on others, so the
// only safe shape is a union. Never compare it numerically.
type Envelope<T> = {
  success: boolean;
  message: string;
  error_code: string | number;
  data: T;
};

const response = await fetch(url, options);
const envelope: Envelope<unknown> = await response.json();

// Branch on success first. Do NOT branch on response.ok alone, and do not
// branch on error_code alone: some failures arrive as HTTP 200 with success
// set to false, and a successful response can still carry error_code 0.
if (!envelope.success) {
  handleFailure(String(envelope.error_code), envelope.message);
  return;
}

use(envelope.data);

error_code comes back as either a string or a number depending on the response: the live system has returned error_code 0 and error_code as a string. Type it as string | number, never compare it numerically, and never branch on error_code alone. Branch on success first, then read the code.

Error codes

The code arrives in the error_code field of the response body.

Request limits

These are the limits that apply to a production key. They are an infrastructure matter rather than a product ceiling.

The two order figures are soft ceilings: going past them makes the computation take considerably longer rather than being refused outright.