Last-mile e-commerce

# (1) Ensure tomorrow's plan exists (idempotent on execution_date + label).
curl -X POST "https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=YOUR_PROJECT_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Daily — 2026-05-22",
    "execution_date": "2026-05-22"
  }'

# (2) Bulk-push the day's orders. Each stop carries phone + email so the
#     customers app at c.routal.com can send tracking links automatically.
curl -X POST "https://api.routal.com/v2/stops?private_key=YOUR_KEY&plan_id=PLAN_ID&project_id=YOUR_PROJECT_ID" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "external_id": "ORD-10042",
      "label": "Alice Doe — 12 Carrer del Bruc",
      "location": { "lat": 41.3955, "lng": 2.1734, "address": "Carrer del Bruc 12, 08010 Barcelona" },
      "duration": 180,
      "time_windows": [[32400, 75600]],
      "phone": "+34600111222",
      "email": "alice@example.com",
      "weight": 1.4,
      "tasks": [
        { "type": "scan",      "label": "Scan tracking barcode" },
        { "type": "signature", "label": "Customer signature" }
      ]
    }
  ]'

# (3) Optimize.
curl -X POST "https://api.routal.com/v2/plan/PLAN_ID/optimize?private_key=YOUR_KEY"

# (4) Dispatch — fire one call per route. The driver gets a magic-link email;
#     the customer auto-gets a tracking link from c.routal.com.
curl -X POST "https://api.routal.com/v2/route/ROUTE_ID/dispatch?private_key=YOUR_KEY"

import createClient from 'openapi-fetch';
import type { paths } from './routal';

const routal = createClient<paths>({ baseUrl: 'https://api.routal.com' });
const ROUTAL_API_KEY = process.env.ROUTAL_API_KEY!;
const PROJECT_ID = process.env.ROUTAL_PROJECT_ID!;

type EcommerceOrder = {
  id: string;               // order number — becomes external_id
  customerName: string;
  addressLine: string;
  lat: number;
  lng: number;
  phoneE164: string;        // E.164, always — Routal validates
  email: string;
  weightKg: number;
  windowFromSec: number;    // e.g. 32400 = 9:00
  windowToSec: number;      // e.g. 75600 = 21:00
};

/** Idempotent: re-running with the same orders is a no-op. */
export async function pushDailyOrders(planId: string, orders: EcommerceOrder[]) {
  if (orders.length === 0) return { created: 0 };

  // 1. De-dup against what's already in the plan (cron retries, deploy windows).
  const existing = await listExternalIdsInPlan(planId);
  const newOnes = orders.filter((o) => !existing.has(o.id));
  if (newOnes.length === 0) return { created: 0 };

  // 2. Chunk by 250 — bulk endpoints accept arrays but very large arrays
  //    become harder to debug if one item fails validation.
  for (let i = 0; i < newOnes.length; i += 250) {
    const chunk = newOnes.slice(i, i + 250);
    const { error } = await routal.POST('/v2/stops', {
      params: { query: { private_key: ROUTAL_API_KEY, plan_id: planId, project_id: PROJECT_ID } },
      body: chunk.map((o) => ({
        external_id: o.id,
        label: `${o.customerName} — ${o.addressLine}`,
        location: { lat: o.lat, lng: o.lng, address: o.addressLine },
        duration: 180,
        time_windows: [[o.windowFromSec, o.windowToSec]],
        phone: o.phoneE164,
        email: o.email,
        weight: o.weightKg,
        tasks: [
          { type: 'scan',      label: 'Scan tracking barcode' },
          { type: 'signature', label: 'Customer signature' },
        ],
      })) as never,
    });
    if (error) throw error;
  }
  return { created: newOnes.length };
}

async function listExternalIdsInPlan(planId: string): Promise<Set<string>> {
  const { data } = await routal.GET('/v2/plan/{id}/stops', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });
  return new Set(((data as Array<{ external_id?: string }>) ?? []).map((s) => s.external_id ?? ''));
}

/** Optimize + dispatch every route in the plan. */
export async function dispatchPlan(planId: string) {
  const { error: optErr } = await routal.POST('/v2/plan/{id}/optimize', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });
  if (optErr) throw optErr;

  const { data: routes } = await routal.GET('/v2/plan/{id}/routes', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });

  for (const route of (routes as Array<{ id: string }>) ?? []) {
    await routal.POST('/v2/route/{id}/dispatch', {
      params: { path: { id: route.id }, query: { private_key: ROUTAL_API_KEY } },
    });
  }
}

import os, requests

ROUTAL_API_KEY = os.environ["ROUTAL_API_KEY"]
PROJECT_ID = os.environ["ROUTAL_PROJECT_ID"]
BASE = "https://api.routal.com"


def list_external_ids_in_plan(plan_id: str) -> set[str]:
    resp = requests.get(
        f"{BASE}/v2/plan/{plan_id}/stops",
        params={"private_key": ROUTAL_API_KEY},
        timeout=30,
    )
    resp.raise_for_status()
    return {s.get("external_id", "") for s in resp.json()}


def push_daily_orders(plan_id: str, orders: list[dict]) -> dict:
    """orders: [{id, customer, address, lat, lng, phone, email, weight_kg, window_from_sec, window_to_sec}, ...]"""
    if not orders:
        return {"created": 0}

    existing = list_external_ids_in_plan(plan_id)
    new_ones = [o for o in orders if o["id"] not in existing]
    if not new_ones:
        return {"created": 0}

    for i in range(0, len(new_ones), 250):
        chunk = new_ones[i:i + 250]
        payload = [
            {
                "external_id": o["id"],
                "label": f"{o['customer']} — {o['address']}",
                "location": {"lat": o["lat"], "lng": o["lng"], "address": o["address"]},
                "duration": 180,
                "time_windows": [[o["window_from_sec"], o["window_to_sec"]]],
                "phone": o["phone"],
                "email": o["email"],
                "weight": o["weight_kg"],
                "tasks": [
                    {"type": "scan",      "label": "Scan tracking barcode"},
                    {"type": "signature", "label": "Customer signature"},
                ],
            }
            for o in chunk
        ]
        resp = requests.post(
            f"{BASE}/v2/stops",
            params={"private_key": ROUTAL_API_KEY, "plan_id": plan_id, "project_id": PROJECT_ID},
            json=payload,
            timeout=60,
        )
        resp.raise_for_status()
    return {"created": len(new_ones)}


def dispatch_plan(plan_id: str) -> None:
    requests.post(
        f"{BASE}/v2/plan/{plan_id}/optimize",
        params={"private_key": ROUTAL_API_KEY},
        timeout=120,
    ).raise_for_status()

    resp = requests.get(
        f"{BASE}/v2/plan/{plan_id}/routes",
        params={"private_key": ROUTAL_API_KEY},
        timeout=30,
    )
    resp.raise_for_status()
    for route in resp.json():
        requests.post(
            f"{BASE}/v2/route/{route['id']}/dispatch",
            params={"private_key": ROUTAL_API_KEY},
            timeout=30,
        ).raise_for_status()