Multi-carrier delivery API

TaxiSaabTaxi owns route selection, carrier offers, payment records, custody and tracking. TTISG uses the same shipment form or this API as any other shipper. No TTISG routing or handover logic is imported.

Shipper workflow

  1. POST /api/v1/network/requests with the pickup, dropoff, parcels, payment, proof and external_reference fields from the delivery API. Use your server-side Bearer credential and a stable Idempotency-Key. This creates an unfunded request and carrier offers.
  2. GET /api/v1/deliveries/{id} or /api/v1/network/deliveries. Every carrier must accept or submit a binding counteroffer before status becomes network_quote. The final sum is delivery.network.total, in the configured currency’s minor units. Quotes expire after 30 minutes from request creation.
  3. POST /api/v1/network/requests/{id}/confirm with {"version":CURRENT_VERSION}. This atomically deducts the exact combined amount from the shipper’s verified prepaid delivery balance. It does not charge a card. Only after confirmation are the segments booked.
  4. Receive signed delivery events through the existing webhook subscription. Pickup creates the tracking reference. Each handover requires outgoing and incoming confirmation. Completion includes the required photo/signature evidence.
  5. Before pickup, POST /api/v1/network/requests/{id}/cancel with the current version. A funded cancellation refunds once. Declined or expired provisional routes take no payment; create a fresh request to choose another route.

Carrier operations

Linked delivery-only accounts use the carrier portal. Shipper API keys cannot accept or counter carrier offers. Carriers see only their own segments and fares; the shipper sees the combined quote and route.

POST /api/v1/network/segments/{id}/{action} with the segment’s current version. Actions: accept, counter (price_minor), decline, pickup (received, package_count, condition), handover (condition), receive (code, received, package_count, condition), arrive, complete (recipient). The handover response returns a single-use code, valid for 30 minutes. The whole shipment transfers only after the receiving carrier checks the code and confirms every package. Do not place access or handover codes in URLs or logs.

Notifications and identity integration

Email links open the carrier portal; GET never accepts work. The portal uses the same versioned POST actions as the app. Native Android notification checks use a separate, revocable, read-only credential. Android schedules background checks; they are not instantaneous push notifications.

The TTISG identity connector sends signed batches of stable carrier/field-operator IDs. It never copies passwords, session cookies, routes or handover data. Set matching strong secrets in TTISG’s TAXISAAB_DELIVERY_SYNC_SECRET and TaxiSaabTaxi’s RDRIVE_TTISG_SYNC_SECRET. Request signature: HMAC-SHA256(secret, timestamp + "." + exact JSON body), sent as X-Delivery-Signature with X-Delivery-Timestamp. Batches contain event_id and up to 50 accounts; each account has id, role, name, email, status, email_verified and a monotonically increasing revision. Replays cannot create duplicate accounts. Unverified or suspended source accounts remain disabled.

Initial service limits

Routes use up to six configured lanes and at most 2,000 enabled lanes. One concurrent committed shipment per lane. The initial implementation supports domestic deliveries in one currency, prepaid delivery fees and no merchandise collection. It uses declared weight and dimensions for capacity checks. Transport timetable matching, customs, currency conversion, partial-package handovers and measured-weight repricing are not implemented. A carrier’s lane availability is an expiry, not a departure schedule.

Configure country policies, real hubs and carrier service lanes before enabling live bookings. Email sending supports the existing TTISG Cloudflare mail configuration through RDRIVE_DELIVERY_MAIL_FILE (a private, read-only mount), or SMTP host, port, sender and credentials. Without a configured transport notifications remain durably queued. Delivery access links expire after 30 days. GPS updates require the current carrier’s delivery page to remain open.