Vendor Dispatch e Portal Magic-Link

Quando seus tecnicos internos nao conseguem alcancar uma task a tempo - uma quebra remota, um buraco de cobertura no fim de semana ou um reparo especializado que voce nao faz internamente - o Levy Service pode entregar o trabalho a um vendor externo. O vendor nunca recebe um login Levy. Ele trabalha por um portal magic-link, sobe fotos e uma fatura, e desaparece.

Quando usar vendor dispatch

Os dois casos mais comuns:

1. Buraco de cobertura geografica - seus tecnicos estao em Mexico Beach, mas o moped quebrado esta a duas horas em Apalachicola
2. Auto-escalacao por breach de SLA - uma task critical ficou sem assignee por 30 minutos, e o rule engine despacha automaticamente a um parceiro proximo

Cadastrando um vendor

Vendors vivem na tabela vendors e sao gerenciados em /dashboard/vendors.

Despachando uma task

Pelo side drawer de qualquer task, clique em Dispatch to Vendor. Um dialog abre com:

• Um vendor picker (filtrado para vendors no raio do veiculo)
• Um campo de texto livre para instrucoes
• Um botao para enviar

No submit:

1. Uma linha vendor_dispatches e escrita
2. Um magic-link token e gerado e enviado para o email de contato do vendor
3. Se o vendor tem webhook URL, um POST assinado vai para la (HMAC-SHA256 sobre o body, segredo em vendors.webhook_secret)
4. A coluna external_vendor_id da task e setada; a superficie do side drawer muda para mostrar status do vendor

O magic link e valido por 7 dias e fica preso a essa task unica - vendors nao podem usar o token para ver suas outras ordens.

O que o vendor ve

O vendor abre o link em qualquer browser. Ele cai em /api/vendor/[token]/tasks e ve:

• Description e priority da task
• Ultima localizacao GPS conhecida do veiculo com um botao "Navigate"
• Campo de upload de foto
• Textarea para resolution notes
• Formulario de fatura (itens + total)

Ele nunca ve outras tasks, outros veiculos, dados de cliente ou qualquer coisa fora do dispatch atribuido.

O fluxo do vendor

1. Vendor abre o magic link
2. Toca em Accept - task vai de assigned para in_progress e a Levy recebe um webhook de volta
3. Dirige ate o veiculo, completa o trabalho
4. Sobe fotos pelo portal
5. Preenche o formulario de fatura e submete

Submeter a fatura escreve uma linha task_vendor_invoices e, se STRIPE_SECRET_KEY estiver configurado, cria uma Stripe Invoice em nome do vendor na sua conta. O custo total do vendor entra automaticamente em tasks.total_cost_cents.

Auto-dispatch dirigido por SLA

A versao mais poderosa de vendor dispatch e a regra que dispara automaticamente.

{
  "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"
  }
}

Configure isso e qualquer task critica que seu time interno nao tenha aceitado em 30 minutos sera entregue automaticamente ao vendor no raio mais proximo. A maior parte das frotas com operacao 24/7 usa para noites e fins de semana.

Payloads de webhook

Se voce conectar um webhook de entrada em /api/webhooks/vendor/[vendor_id], o sistema do vendor pode empurrar updates de status e faturas sem passar pelo portal. O endpoint espera assinatura HMAC-SHA256 no header X-Levy-Signature. Eventos suportados: task.accepted, task.in_progress, task.resolved, task.invoice_uploaded.

O segredo do vendor fica em vendors.webhook_secret e e rotacionado pela pagina de edicao do vendor.

Custos e reconciliacao

Vendor invoices aparecem em tres lugares no dashboard:

• Task detail - link do PDF da fatura no side drawer
• Vehicle lifetime cost - somado ao total por veiculo
• Monthly P&L - barra empilhada separada de "vendor cost" no grafico de analytics

Se Stripe estiver configurado, cada fatura tambem e uma Stripe Invoice real que o vendor pode pagar (ou que voce pode pagar a ele, dependendo do lado da relacao). O ID da Stripe Invoice fica em task_vendor_invoices.stripe_invoice_id para reconciliacao.

Nota de fase

Vendor dispatch e a entrega da Fase 4. E dependente de parceria - ou seja, o rule engine e o portal magic-link estao live para qualquer frota, mas parcerias com vendors especificos (estilo Velofix) sao negociadas por regiao. Fale com seu CSM Levy se quiser um parceiro nomeado no seu mercado.