Adicione Planejamento de Trajetos à Sua Plataforma

Visão Geral

Cada nível funciona por conta própria. A maioria dos parceiros começa no Nível 1 (Lançamento em Um Clique) e adiciona níveis superiores depois, conforme as necessidades mudam. As seções abaixo descrevem o que seus usuários finais experimentam, o que você ganha como empresa, o detalhamento completo dos quatro níveis e um aprofundamento no Nível 1. A seção Detalhes Técnicos mais adiante contém a especificação de engenharia.

O Que Seus Usuários Experimentam

No Nível 1, o Launch Pad funciona como um aplicativo complementar ao seu produto. Ele abre em uma nova janela do navegador com toda a preparação feita em segundo plano, para que o usuário possa começar a trabalhar imediatamente.

O Que Você Ganha Como Parceiro

Feito para empresas e equipes de engenharia que querem incorporar roteirização de precisão sem precisar montar a infraestrutura que a sustenta.

Quatro Níveis de Integração

Cada nível funciona por conta própria. A maioria dos parceiros começa no Nível 1 e adiciona níveis superiores depois, conforme as necessidades mudam.

Como o Nível 1 Elimina a Fricção

Por Que o Nível 1 Existe

Modelo de Conta

Um engajamento de Nível 1 é organizado assim:

O Que os Usuários Veem no Launch Pad

Quando um usuário abre o Launch Pad pelo Nível 1, algumas opções do Launch Pad não se aplicam e ficam ocultas:

• Sem troca de senha, sem gerenciamento de e-mail ou conta, sem cadastro. O usuário não tem senha do Launch Pad; o login vem do seu produto. A tela de troca de senha mostra uma mensagem "Senha gerenciada pelo [Parceiro]", igual à forma como o Launch Pad já lida com usuários que entram via John Deere, Trimble ou CNH.
• Sem seletor de empresa. A sessão fica travada em uma única organização de cliente para aquela visita.
• Logout é substituído por "Voltar para [Parceiro]", que fecha a aba ou envia o usuário de volta a uma URL que você fornece, em vez de deixá-lo na tela de login do Launch Pad.

O menu principal de trabalho (Planos, Planejamento de Trajetos, Equipamentos, Comparar) continua disponível porque os usuários precisam dele para fazer a tarefa. Só ficam ocultas as opções de identidade, faturamento, administração e gestão de conta.

Devolução do Plano de Trajeto

Depois que um usuário finaliza um plano de trajeto no Launch Pad, o resultado precisa voltar para o seu produto. Quatro opções estão disponíveis e funcionam em cima de qualquer nível. Opções de push são fortemente preferíveis a polling.

Fluxo Ponta a Ponta

O que acontece, passo a passo, quando um usuário do parceiro abre o Launch Pad:

sequenceDiagram
    autonumber
    participant YU as UI do Parceiro
    participant YB as Backend do Parceiro
    participant LA as Launch Pad API
    participant LU as Launch Pad UI

    YU->>YB: usuário clica em "Abrir Plano de Trajeto"

    note over YB,LA: Etapa 1: criar usuário do LP se não existir
    YB->>LA: POST /api/users (idempotente em externalUserId)
    YB->>LA: POST /api/company-accesses (idempotente em usuário + org)

    note over YB,LA: Etapa 2 (opcional): enviar um talhão
    YB->>LA: POST /api/vBoundary/upsert

    note over YB,LA: Etapa 3: solicitar um código de lançamento
    YB->>LA: POST /api/partner/launch ({ userId, companyId, returnUrl })
    LA-->>YB: { code, expiresInSec: 600 }

    YB-->>YU: 302 redireciona para https://your-app.vergeag.com/launch?code=...
    YU->>LU: navegador navega para /launch?code=...
    LU->>LA: POST /api/partner/launch/{code}/exchange
    LA-->>LU: JWT + refresh token
    note over LU: armazena JWT no localStorage,
remove o código da URL,
navega para returnUrl
          

Propriedades Principais

• Você autentica servidor-a-servidor com uma credencial de longa duração (a API key do seu usuário administrador). O navegador nunca vê a API key.
• O navegador só vê um código opaco, de uso único e curta duração na URL (time-to-live de 10 minutos, consumido na troca).
• O endpoint de troca não exige login; o próprio código é a credencial. A UI do Launch Pad o chama assim que o usuário chega.
• O Launch Pad emite uma sessão de usuário normal (JWT + refresh token), armazena no localStorage e direciona o usuário para a URL que você especificou.

Alinhamento com Padrões

Como É a URL de Redirecionamento

O que o navegador do usuário recebe (uma linha, como cabeçalho Location:):

https://your-app.vergeag.com/launch?code=lc_R3w9q-Kx7VtNm2bH8sLpYj4eQ6gZc1aXfU0dT5nMoP&returnUrl=%2Fpath-planning%2Fboundary%2Fb3f47e1c-8a02-4d59-9c6e-2f7a8b1d6e09

Decodificada para leitura:

O Que a UI do Launch Pad Faz ao Chegar

Você não implementa isso; está aqui só como referência para você raciocinar sobre o que seus usuários veem entre o clique e o talhão renderizado:

1. Lê code e returnUrl da query string.
2. Troca o código com o Launch Pad por uma sessão de usuário.
3. Autentica o usuário na organização de cliente correta.
4. Remove o código da barra de endereço para que ele não fique no histórico do navegador.
5. Envia o usuário para o returnUrl que você especificou.

Se code estiver ausente, expirado ou já consumido, o usuário vai parar em uma página de erro que pede para voltar ao seu produto e tentar de novo.

Opções de Devolução em Detalhe

Níveis Superiores

Esta página é a referência completa para o Nível 1. Para níveis superiores: