Reverse logistics — pickups & returns

# (1) Push a mixed batch — one delivery stop and one paired pickup stop
#     at the same supermarket, chained so they end up on the same vehicle.
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": "DEL-90100",
      "label": "BigMart — Calle Mayor 14 — delivery",
      "location": { "lat": 40.4153, "lng": -3.7079, "address": "Calle Mayor 14, 28013 Madrid" },
      "duration": 900,
      "time_windows": [[28800, 43200]],
      "weight": 320,
      "volume": 2.4,
      "chain_id": "VISIT-BIGMART-MAYOR-14-2026-05-22",
      "chain_position": 0
    },
    {
      "external_id": "PICKUP-RMA-44521",
      "label": "BigMart — Calle Mayor 14 — empty pallets pickup",
      "location": { "lat": 40.4153, "lng": -3.7079, "address": "Calle Mayor 14, 28013 Madrid" },
      "duration": 600,
      "time_windows": [[28800, 43200]],
      "weight": 180,
      "volume": 1.8,
      "chain_id": "VISIT-BIGMART-MAYOR-14-2026-05-22",
      "chain_position": 1
    }
  ]'

# (2) Optimize. The vehicle's default_max_weight covers loaded outbound goods
#     AND collected inbound empties simultaneously — set it generously.
curl -X POST "https://api.routal.com/v2/plan/PLAN_ID/optimize?private_key=YOUR_KEY"

# (3) Dispatch.
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 ReverseStop = {
  id: string;
  kind: 'delivery' | 'pickup';
  customer: string;
  lat: number;
  lng: number;
  address: string;
  weightKg: number;
  volumeM3: number;
  windowFromSec: number;
  windowToSec: number;
  durationSec: number;
  /** If pickup + delivery share a customer visit, give both the same chainId. */
  chainId?: string;
};

/** Push a batch of stops with chained delivery+pickup pairs. */
export async function pushDailyMixed(planId: string, stops: ReverseStop[]) {
  // Group by chain — for each chain, assign chain_position by 'delivery'-first.
  const byChain = new Map<string, ReverseStop[]>();
  const standalone: ReverseStop[] = [];
  for (const s of stops) {
    if (!s.chainId) standalone.push(s);
    else byChain.set(s.chainId, [...(byChain.get(s.chainId) ?? []), s]);
  }

  type StopPayload = {
    external_id: string;
    label: string;
    location: { lat: number; lng: number; address: string };
    duration: number;
    time_windows: [number, number][];
    weight: number;
    volume: number;
    chain_id?: string;
    chain_position?: number;
  };

  const payload: StopPayload[] = [];
  for (const s of standalone) {
    payload.push(toPayload(s));
  }
  for (const group of byChain.values()) {
    // Deliveries before pickups on the same chain.
    group.sort((a, b) => Number(a.kind === 'pickup') - Number(b.kind === 'pickup'));
    group.forEach((s, idx) => {
      payload.push({ ...toPayload(s), chain_id: s.chainId, chain_position: idx });
    });
  }

  for (let i = 0; i < payload.length; i += 250) {
    const chunk = payload.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 as never,
    });
    if (error) throw error;
  }
}

function toPayload(s: ReverseStop) {
  return {
    external_id: s.id,
    label: `${s.customer} — ${s.kind}`,
    location: { lat: s.lat, lng: s.lng, address: s.address },
    duration: s.durationSec,
    time_windows: [[s.windowFromSec, s.windowToSec]] as [number, number][],
    weight: s.weightKg,
    volume: s.volumeM3,
  };
}

import os, requests

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


def to_payload(s: dict) -> dict:
    return {
        "external_id": s["id"],
        "label": f"{s['customer']} — {s['kind']}",
        "location": {"lat": s["lat"], "lng": s["lng"], "address": s["address"]},
        "duration": s["duration_sec"],
        "time_windows": [[s["window_from_sec"], s["window_to_sec"]]],
        "weight": s["weight_kg"],
        "volume": s["volume_m3"],
    }


def push_daily_mixed(plan_id: str, stops: list[dict]) -> None:
    """Push delivery + pickup stops; chain pairs that share a chain_id."""
    by_chain: dict[str, list[dict]] = {}
    standalone: list[dict] = []
    for s in stops:
        if not s.get("chain_id"):
            standalone.append(s)
        else:
            by_chain.setdefault(s["chain_id"], []).append(s)

    payload = [to_payload(s) for s in standalone]

    for chain_id, group in by_chain.items():
        # Deliveries before pickups within the same chain.
        group.sort(key=lambda x: 1 if x["kind"] == "pickup" else 0)
        for idx, s in enumerate(group):
            item = to_payload(s)
            item["chain_id"] = chain_id
            item["chain_position"] = idx
            payload.append(item)

    for i in range(0, len(payload), 250):
        chunk = payload[i:i + 250]
        requests.post(
            f"{BASE}/v2/stops",
            params={"private_key": ROUTAL_API_KEY, "plan_id": plan_id, "project_id": PROJECT_ID},
            json=chunk,
            timeout=60,
        ).raise_for_status()