Vendor Dispatch and Magic-Link Portal

When your internal techs cannot reach a task in time — a remote breakdown, a weekend gap in coverage, or a specialized repair you do not handle in-house — Levy Service can hand the work to an external vendor. The vendor never gets a Levy login. They work through a magic-link portal, upload photos and an invoice, and disappear.

When to use vendor dispatch

The two most common use cases:

1. Geographic coverage gap — your techs are in Mexico Beach but the broken-down moped is two hours away in Apalachicola
2. SLA breach auto-escalation — a critical task has been unclaimed for 30 minutes and the rule engine auto-dispatches to a nearby partner

Adding a vendor

Vendors live in the vendors table and are managed at /dashboard/vendors.

Dispatching a task

From any task's side drawer, click Dispatch to Vendor. A dialog opens with:

• A vendor picker (filtered to vendors within range of the vehicle)
• A free-text instruction field
• A button to send

On submit:

1. A vendor_dispatches row is written
2. A magic-link token is minted and emailed to the vendor's contact address
3. If the vendor has a webhook URL, a signed POST goes to it (HMAC-SHA256 over the request body, secret in vendors.webhook_secret)
4. The task's external_vendor_id column is set; the side drawer surface shifts to show vendor status

The magic link is good for 7 days and stays bound to that single task — vendors cannot use it to see your other work.

What the vendor sees

The vendor opens the link in any browser. They land on /api/vendor/[token]/tasks and see:

• The task description and priority
• The vehicle's last known GPS location with a "Navigate" button
• A photo upload field
• A textarea for resolution notes
• An invoice form (line items + total)

They never see other tasks, other vehicles, customer data, or anything outside their assigned dispatch.

The vendor flow

1. Vendor opens the magic link
2. Taps Accept — task moves from assigned to in_progress and Levy gets a webhook back
3. Drives to the vehicle, completes the work
4. Uploads photos through the portal
5. Fills the invoice form and submits

Submitting the invoice writes a task_vendor_invoices row and, if STRIPE_SECRET_KEY is configured, creates a Stripe Invoice in the vendor's name on your account. The vendor's total cost rolls into tasks.total_cost_cents automatically.

SLA-driven auto-dispatch

The most powerful version of vendor dispatch is the rule that fires it automatically.

{
  "trigger_type": "time",
  "trigger_config": {
    "cron": "every 5 minutes",
    "condition": "task.status = 'created' AND task.created_at < NOW() - INTERVAL '30 min' AND task.priority IN ('high', 'critical')"
  },
  "action_config": {
    "escalate_to_vendor": "nearest"
  }
}

Set this up and any critical task your internal team hasn't claimed within 30 minutes will be handed to the closest in-range vendor automatically. Most fleets running 24/7 ops use this for nights and weekends.

Webhook payloads

If you wire up an inbound webhook at /api/webhooks/vendor/[vendor_id], the vendor's system can push status updates and invoices without going through the portal. The endpoint expects HMAC-SHA256 signature in the X-Levy-Signature header. Supported events: task.accepted, task.in_progress, task.resolved, task.invoice_uploaded.

The vendor's secret is stored in vendors.webhook_secret and rotated through the vendor edit page.

Costs and reconciliation

Vendor invoices appear on the dashboard in three places:

• Task detail — invoice PDF link in the side drawer
• Vehicle lifetime cost — added to the per-vehicle total
• Monthly P&L — separate "vendor cost" stacked bar in the analytics chart

If Stripe is configured, each invoice is also an actual Stripe Invoice that the vendor can pay (or that you can pay them, depending on which side of the relationship you're on). The Stripe Invoice ID is stored in task_vendor_invoices.stripe_invoice_id for reconciliation.

Phase note

Vendor dispatch is the Phase 4 deliverable. It is partnership-gated — meaning the rule engine and magic-link portal are live for any fleet, but specific vendor partnerships (Velofix-style) are negotiated per region. Talk to your Levy CSM if you want a named partner in your market.