Skip to content
Navo24Navo24

Guias

Incorporar as apps Navo no site de um cliente

Incorpore rastreamento de contêineres no seu site, além de cotações de frete, escalas marítimas e modo AI, com sua marca, uma tag de script e chave vinculada ao domínio.

Você pode incorporar o rastreamento de contêineres no próprio site de um cliente, junto com tarifas de frete e programações de embarque. São os mesmos apps que você vê no site de exemplo de um agente de carga: um widget de busca para a página inicial, além de uma página completa para cada app. Cada um aparece com o nome, o logo e a cor do cliente. Cada visualização tem seu próprio link, para que um visitante possa enviar a um colega um contêiner, uma busca de tarifa, uma tarifa, uma programação de embarque, um navio ou um porto, e tudo abre no site do cliente.

Nenhuma API key ou servidor é necessário do lado do cliente. A chave de incorporação é pública e funciona apenas nos domínios que listamos para ela.

O que o cliente nos envia

ItemExemploObrigatório
Nome da empresa como os visitantes devem vê-loAcme LogisticsSim
Domínios em que os apps serão executados (produção, staging)acme.com, www.acme.com, staging.acme.comSim
Logo, SVG ou PNG, marca quadrada ou horizontalhttps://acme.com/logo.svgSim
Cor da marca, um valor hex#0e6ba8Sim
Mais cores, fontes, arredondamento de cantosveja AparênciaOpcional
E-mail que recebe solicitações de reserva[email protected]Para tarifas de frete
URL de webhook para solicitações de reserva (para o CRM/TMS deles)https://acme.com/hooks/navoOpcional
Quais apps eles queremqualquer combinação de tracking, freight, schedules; modo de IA ativado ou desativadoSim
Limite de uso por app, por mês ou por anotracking: 300 embarques únicos por mêsSim
Páginas onde cada app ficará/track, /rates, /schedulesRecomendado
“Desenvolvido por Navo” exibido ou ocultoexibidoPadrão: exibido

Criamos a chave e enviamos de volta os snippets abaixo, com a chave preenchida.

O que uma chave pode carregar

Uma chave abre um app ou vários, e o modo de IA é um switch separado:

PacoteApps na chaveO que o visitante recebe
Apenas trackingtrackingPágina de tracking; o widget de busca mostra a caixa de tracking sem abas e sem switch de IA
Tracking com IAtracking, aiO mesmo, mais o modo de IA no widget de busca e “Perguntar à IA” nos embarques
Tarifas e programaçõesfreight, schedulesDuas abas no widget de busca, as páginas de tarifas e programações
Tudotracking, freight, schedules, aiAs três abas, modo de IA, todas as páginas

O widget é construído a partir da chave: uma aba, uma página ou um botão de IA que a chave não abre não é desenhado, e nosso servidor recusa seus dados mesmo que alguém force a requisição.

Limites de uso

Cada app em uma chave tem seu próprio limite, por mês-calendário ou por ano-calendário (UTC). O que conta como uma unidade:

AppUma unidadeRepetições grátis
trackingUm embarque único (número de contêiner, booking ou B/L)O mesmo embarque pelo restante do período
freightUma busca de tarifa (rota e equipamento)A mesma busca no mesmo dia
schedulesUma busca de programação (rota, navio ou porto)A mesma busca no mesmo dia
aiUma pergunta ao assistente de IANenhuma

Exemplo: tracking em 300 embarques únicos por mês. Os visitantes do cliente podem abrir e atualizar esses 300 embarques quantas vezes quiserem durante todo o mês; o embarque 301 é recusado até o dia 1 do mês seguinte. Quando um app atinge seu limite, os visitantes veem “Este serviço está pausado neste site por enquanto. Entre em contato com .” Os outros apps na chave continuam funcionando. Vemos o uso por app e podemos aumentar um limite a qualquer momento, sem nenhuma alteração no site do cliente.

Instalação

Coloque o loader uma vez em cada página que mostra um app:

<script src="https://navo24.com/embed.js" async></script>

Depois, um contêiner onde o app deve aparecer.

Widget de busca (hero da página inicial, ou qualquer página). Uma caixa com uma aba para cada app na chave (tracking, tarifas, programações) e modo de IA se a chave tiver. Com um app só, não há abas:

<div
  data-navo-app="search"
  data-navo-key="nve_YOUR_KEY"
  data-navo-pages='{"tracking":"/track","freight":"/rates","schedules":"/schedules"}'
></div>

Com data-navo-pages, o widget envia os visitantes para as próprias páginas do cliente. Sem ele, o resultado abre dentro do frame do widget.

Página de tracking (/track):

<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>

Página de tarifas de frete (/rates):

<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>

Página de programações de embarque (/schedules), com três abas: por rota, por navio, por porto:

<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>

Use o mesmo valor de data-navo-pages em todos os apps para que links cruzados (por exemplo “Mostrar tarifas” em uma programação de embarque, ou “Programação do navio” em um embarque) cheguem à página correta do site do cliente.

Opções

AtributoO que faz
data-navo-appsearch, tracking, freight ou schedules.
data-navo-keyA chave de incorporação do site.
data-navo-pagesMapa JSON de app para caminho de página no site do cliente.
data-navo-heightAltura fixa em px. Por padrão, o frame cresce com seu conteúdo; tracking é um mapa completo, 680 px.
data-navo-syncoff mantém a URL da página inalterada enquanto o visitante navega.
data-navo-themeJSON com cores, fontes e cantos, veja Aparência.

Sites com Content Security Policy

Se o site envia um cabeçalho Content-Security-Policy (ou um <meta http-equiv>) com script-src ou frame-src, adicione navo24.com a ambos, caso contrário o navegador bloqueia o loader ou o frame e o contêiner fica vazio:

script-src ... https://navo24.com;
frame-src  ... https://navo24.com;

Com child-src em vez de frame-src, adicione ali. Nada mais é necessário: os apps carregam seus dados, fontes e mapas dentro do frame, sob nossa própria política. O console do navegador informa a diretiva bloqueada se alguma estiver faltando.

Eventos para analytics e CRM

O contêiner dispara eventos DOM quando um visitante faz algo, para que o site possa enviá-los ao Google Analytics, a um gerenciador de tags ou ao seu CRM. Eles fazem bubble, então um listener em document captura todos os apps na página.

EventoQuandoevent.detail
navo:searchUma busca retornou resultadosapp (tracking, freight, schedules) e a consulta: ref, ou origin, destination, container
navo:bookingUma solicitação de reserva foi enviadareference, origin, destination, container, quantity, carrier, price, currency
navo:limitUm limite interrompeu uma buscaapp, code (por exemplo site_busy, rate_limited)
<script>
  document.addEventListener('navo:search', (e) => gtag('event', 'navo_search', e.detail));
  document.addEventListener('navo:booking', (e) => gtag('event', 'generate_lead', { value: e.detail.price, currency: e.detail.currency, transaction_id: e.detail.reference }));
</script>

Os dados de contato do visitante não ficam nos eventos: eles vão apenas para o e-mail de reserva e para o webhook.

Aparência

Por padrão, os apps pegam a cor da marca do cliente a partir da chave. Para combinar melhor com o site, adicione data-navo-theme ao contêiner: cores, fontes, arredondamento de cantos e modo escuro.

<div
  data-navo-app="freight"
  data-navo-key="nve_YOUR_KEY"
  data-navo-theme='{"accent":"#e4002b","text":"#1a1a1a","heading":"#002f6c","font":"Inter","radius":6,"buttonRadius":6}'
></div>

Todas as chaves são opcionais. Um valor inválido é ignorado, o restante ainda é aplicado.

ChaveO que alteraExemplo
accentBotões, links, abas ativas, switches, anel de foco. Tons de hover e pressionado são calculados a partir dela"#e4002b"
textTexto principal"#1a1a1a"
mutedTexto secundário: rótulos, dicas, datas"#6b7280"
headingTítulos, nomes de transportadoras e navios, linhas do mapa"#002f6c"
backgroundFundo da página do app. "transparent" deixa o fundo do próprio cliente aparecer"#ffffff"
surfaceCards, inputs, listras de tabela"#f5f7fa"
borderBordas e divisores"#e5e7eb"
successEstados positivos: entregue, no prazo, mais barato"#15803d"
radiusArredondamento de cantos de cards e painéis, px (0 a 40)8
buttonRadiusArredondamento de cantos de botões e inputs, px. 999 cria pílulas (o padrão)6
fontFonte do corpo. Qualquer família do Google Fonts é carregada para você; "system" usa a fonte do sistema do visitante"Inter"
headingFontFonte para títulos, mesmas regras. Sem ela, os títulos usam font"Playfair Display"
fontCssSua própria folha de estilos de fontes (URL https:// com regras @font-face), para fontes que não estão no Google Fonts. Então font e headingFont nomeiam famílias desse arquivo"https://acme.com/fonts/brand.css"
mode"dark" para sites com design escuro"dark"

As cores são hex: #rgb, #rrggbb ou #rrggbbaa.

Pontos de partida prontos:

<!-- Corporate: square corners, navy headings -->
data-navo-theme='{"accent":"#003a70","heading":"#003a70","font":"Source Sans 3","radius":2,"buttonRadius":2}'

<!-- Soft: rounded, light grey cards -->
data-navo-theme='{"accent":"#0f766e","surface":"#f3f4f6","font":"Nunito","radius":16,"buttonRadius":999}'

<!-- Dark site -->
data-navo-theme='{"mode":"dark","accent":"#f59e0b","background":"#0b1220","surface":"#111a2e","border":"#1f2a44","text":"#e5e7eb","muted":"#94a3b8"}'

<!-- Blend into the page: the app draws no background of its own -->
data-navo-theme='{"background":"transparent","font":"system"}'

Um tema para todas as páginas. Também podemos armazenar o tema na chave. Então todo contêiner em toda página recebe esse tema sem o atributo, e podemos ajustá-lo depois sem mudança no site do cliente. data-navo-theme em um contêiner ainda prevalece sobre o tema da chave, chave por chave.

O tema só chega ao app dentro do frame: ele nunca altera a própria página do cliente.

React e Next.js, com indexação de busca

Use isto quando o site do cliente é construído com React ou Next.js e o conteúdo do app deve ser indexado como a página do cliente (por exemplo, uma página por rota, “Shanghai to Hamburg sailing schedule”).

São duas partes:

  1. Snapshot. O servidor do cliente busca os dados da rota conosco como HTML simples (tabela de programação ou tabela de tarifas, um título, um resumo de uma linha e marcação schema.org) e coloca isso em sua própria página. Mecanismos de busca indexam como conteúdo do cliente, na URL do cliente.
  2. App. No navegador, o app interativo é montado acima disso, com busca, filtros, detalhes e reserva. O snapshot permanece na página como uma tabela recolhível sob o app, para que crawlers e visitantes vejam o mesmo conteúdo.

Endpoint de snapshot

GET https://api.navo24.com/v1/demo/embed/snapshot
    ?key=nve_YOUR_KEY
    &app=schedules            schedules | freight
    &origin=CNSHA             UN/LOCODE
    &destination=DEHAM        UN/LOCODE
    &container=40HC           freight only: 20GP | 40GP | 40HC
    &host=acme.com            the client's domain, must be on the key
    &format=html              optional: the HTML block only

Sem format=html, a resposta é JSON:

{
  "data": {
    "app": "schedules",
    "title": "Sailing schedule Shanghai to Hamburg",
    "description": "153 sailings from Shanghai (CNSHA) to Hamburg (DEHAM) in the next 6 weeks, 10 carriers, transit from 34 days.",
    "items": [{ "carrier": "Yang Ming", "vessel": "MSC OLIVIA", "voyage": "GL642W", "etd": "2026-10-24T00:00:00", "eta": "2026-12-03T00:00:00", "transit_days": 40, "direct": true }],
    "html": "<section class=\"navo-snapshot\">…</section>",
    "as_of": "2026-10-22T08:52:51Z"
  }
}

Use title e description para o <title> da página e a meta description, html para o corpo. A resposta pode ser armazenada em cache por 30 minutos (Cache-Control: max-age=1800). Um snapshot conta como uma busca contra o limite do app; a mesma rota no mesmo dia é grátis. Tracking não tem snapshot: embarques são privados para o visitante.

Next.js (App Router)

// app/schedules/[lane]/page.tsx   e.g. /schedules/cnsha-deham
import NavoApp from './NavoApp';

const KEY = 'nve_YOUR_KEY';
const API = 'https://api.navo24.com/v1/demo/embed/snapshot';

async function snapshot(lane: string) {
  const [origin, destination] = lane.toUpperCase().split('-');
  const q = new URLSearchParams({ key: KEY, app: 'schedules', origin, destination, host: 'acme.com' });
  const r = await fetch(`${API}?${q}`, { next: { revalidate: 1800 } });
  return r.ok ? (await r.json()).data : null;
}

export async function generateMetadata({ params }: { params: { lane: string } }) {
  const s = await snapshot(params.lane);
  return s ? { title: `${s.title} | Acme Logistics`, description: s.description } : {};
}

export default async function Page({ params }: { params: { lane: string } }) {
  const s = await snapshot(params.lane);
  const [origin, destination] = params.lane.toUpperCase().split('-');
  return (
    <main>
      <NavoApp
        app="schedules"
        embedKey={KEY}
        view={{ origin, destination }}
        snapshotHtml={s?.html}
        theme={{ accent: '#e4002b', font: 'Inter' }}
      />
    </main>
  );
}
// app/schedules/[lane]/NavoApp.tsx
'use client';
import { useEffect, useRef, useState } from 'react';

const SRC = 'https://navo24.com/embed.js';

function loadNavo(): Promise<void> {
  const w = window as any;
  if (w.NavoEmbed) return Promise.resolve();
  return new Promise((ok) => {
    let s = document.querySelector<HTMLScriptElement>(`script[src="${SRC}"]`);
    if (!s) { s = document.createElement('script'); s.src = SRC; s.async = true; document.head.appendChild(s); }
    s.addEventListener('load', () => ok(), { once: true });
  });
}

type Props = {
  app: 'search' | 'tracking' | 'freight' | 'schedules';
  embedKey: string;
  view?: Record<string, string>;          // opens this lane right away
  pages?: Record<string, string>;
  theme?: Record<string, string | number>;
  snapshotHtml?: string;                  // server-rendered data for search engines
};

export default function NavoApp({ app, embedKey, view, pages, theme, snapshotHtml }: Props) {
  const box = useRef<HTMLDivElement>(null);
  const [live, setLive] = useState(false); // until the app is up, the table is open
  useEffect(() => {
    if (view && !new URLSearchParams(location.search).get('navo')) {
      const u = new URL(location.href);
      u.searchParams.set('navo_app', app);
      u.searchParams.set('navo', new URLSearchParams(view).toString());
      history.replaceState(history.state, '', u);
    }
    loadNavo().then(() => { (window as any).NavoEmbed.mount(); setLive(true); });
  }, [app, embedKey]);
  return (
    <>
      <div
        ref={box}
        data-navo-app={app}
        data-navo-key={embedKey}
        data-navo-pages={pages ? JSON.stringify(pages) : undefined}
        data-navo-theme={theme ? JSON.stringify(theme) : undefined}
      />
      {snapshotHtml && (
        <details open={!live}>
          <summary>All results as a table</summary>
          <div dangerouslySetInnerHTML={{ __html: snapshotHtml }} />
        </details>
      )}
    </>
  );
}

Como isso aparece para um mecanismo de busca: o próprio título e a descrição da página, um título e uma tabela completa de programações de embarque (ou tarifas) no HTML, com marcação Dataset. Como aparece para um visitante: o app ao vivo, já aberto naquela rota, com os mesmos resultados como uma tabela recolhida abaixo dele. Visitantes com JavaScript desligado veem a tabela aberta. A tabela é recolhida, não oculta, então a página não mostra aos crawlers nada que um visitante não possa abrir.

O HTML do snapshot vem do nosso servidor com todos os valores escapados, então é seguro inseri-lo. Estilize com as classes .navo-snapshot e .navo-snapshot-table se ele algum dia for mostrado.

Outros frameworks de servidor (Remix, Astro, Nuxt, PHP, WordPress) funcionam da mesma forma: busque o snapshot no servidor, imprima html na página, coloque o contêiner ao lado.

React puro (sem renderização no servidor)

Quando a indexação de busca não importa (uma página de tracking atrás de um menu, uma intranet), o componente sem o snapshot é suficiente:

O loader funciona da mesma forma em um app de página única (React, Vue, Svelte): renderize o contêiner, depois chame window.NavoEmbed.mount().

import { useEffect } from 'react';

const SRC = 'https://navo24.com/embed.js';

function loadNavo() {
  if (window.NavoEmbed) return Promise.resolve();
  return new Promise((ok) => {
    let s = document.querySelector(`script[src="${SRC}"]`);
    if (!s) { s = document.createElement('script'); s.src = SRC; s.async = true; document.head.appendChild(s); }
    s.addEventListener('load', ok, { once: true });
  });
}

export function NavoApp({ app, embedKey, pages }) {
  useEffect(() => { loadNavo().then(() => window.NavoEmbed.mount()); }, [app, embedKey]);
  return (
    <div
      data-navo-app={app}
      data-navo-key={embedKey}
      data-navo-pages={pages ? JSON.stringify(pages) : undefined}
    />
  );
}

// <NavoApp app="tracking" embedKey="nve_YOUR_KEY" pages={{ tracking: '/track' }} />

No Next.js, coloque em um componente cliente ('use client').

Por que um frame

O loader desenha cada app dentro de um frame de navo24.com. É assim que Stripe Checkout, incorporações do Google Maps e players do YouTube funcionam, pelos mesmos motivos:

  • Bloqueio por domínio. O próprio navegador se recusa a mostrar o app em um site que não está na lista da chave (frame-ancestors). Um componente de script carregado na página do cliente não pode ser bloqueado dessa forma.
  • Sem conflitos de estilo. O CSS do cliente não pode quebrar o app e nosso CSS não pode tocar no site dele.
  • Atualizações sem o cliente. Novas transportadoras, correções e recursos chegam a todos os sites no mesmo dia; nada para atualizar do lado do cliente.
  • Mecanismos de busca. Conteúdo dentro de um frame não é indexado como página do cliente, assim como qualquer mapa ou vídeo incorporado. Quando isso importa, adicione o snapshot renderizado no servidor, veja React e Next.js, com indexação de busca.

Visitantes não fazem login dentro do frame, então o bloqueio de cookies de terceiros pelo navegador não o afeta.

Enquanto um visitante trabalha em um app, a URL da página o acompanha: ?navo_app=<app>&navo=<view>. Os botões Copiar link dentro dos apps produzem o mesmo tipo de link. Exemplos em uma página de cliente /rates:

VisualizaçãoLink
Um contêiner/track?navo_app=tracking&navo=ref%3DZMOU8956106
Busca de tarifa em uma rota/rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC
Uma tarifaa busca acima mais %26quote%3D<id>
Busca de programação em uma rota/schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM
Uma programaçãoa busca acima mais %26sailing%3D<id>
Um navio/schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890
Um porto/schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN

Uma tarifa ou programação compartilhada continua abrindo depois de sair dos resultados ao vivo; ela é mostrada com a data em que seus dados foram obtidos.

Solicitações de reserva

Reservar em uma tarifa abre um formulário de solicitação (contato, empresa, e-mail, telefone, número de contêineres, data de carga pronta, carga, observações). Ao enviar:

  • um e-mail vai para o endereço de reservas do cliente, com a rota, equipamento, transportadora, o preço que o visitante viu e os dados de contato do visitante. Reply-To é o visitante, então o cliente responde direto da própria caixa de e-mail;
  • se um webhook estiver configurado, a mesma solicitação é enviada via POST para ele como JSON:
{
  "type": "booking.requested",
  "data": {
    "reference": "BR-261020-4F2A1",
    "received_at": "2026-10-20T14:05:11Z",
    "site": "acme.com",
    "contact": { "name": "…", "company": "…", "email": "…", "phone": "…" },
    "shipment": { "origin": "Shanghai (CNSHA)", "destination": "Hamburg (DEHAM)", "container": "40ft HC", "quantity": "2", "ready_date": "2026-11-03", "cargo": "…", "notes": "…" },
    "rate": { "id": "…", "carrier": "…", "price": 2140, "currency": "USD", "transit_days": 34, "departure": "2026-11-06", "valid_until": "2026-11-15" }
  }
}

O visitante vê uma confirmação com a referência. Nada é cobrado e nenhuma reserva com transportadora é feita: o cliente confirma espaço e responde.

Sem e-mail de reserva ou webhook, o formulário permanece como demonstração e informa isso.

O que os visitantes veem, e o que não veem

  • Nomes e logos de transportadoras, preços, tempos de trânsito, validade e o que uma tarifa inclui.
  • Tarifas sem transportadora nomeada são mostradas como ” Select”, com o logo do cliente.
  • Fontes e plataformas de tarifas nunca são mostradas. Elas são removidas em nosso servidor antes que os dados cheguem ao navegador.

Segurança

Bloqueio por domínio. As páginas do app respondem com Content-Security-Policy: frame-ancestors listando apenas os domínios da chave, então um navegador se recusa a mostrá-las em qualquer outro lugar. Requisições de dados carregam a chave e o host da página pai, e são recusadas quando o host não está na lista. Uma chave copiada para outro site não funciona lá.

Limites. Cada app em uma chave tem seu próprio limite mensal ou anual (veja Limites de uso). Além disso, toda chave tem um limite de segurança de 50,000 requisições por mês, um teto de 600 requisições por minuto para o site inteiro (para que um pico de tráfego de um site não deixe os apps mais lentos para outros; aumentado sob solicitação) e limites por visitante contra abuso automatizado; acima disso, o app mostra uma mensagem curta de “tente novamente” e dispara navo:limit.

Mensagens. O frame e o loader conversam por postMessage, e cada lado envia apenas para a origem exata do outro: o frame para a página do cliente, o loader para navo24.com. Detalhes de busca nunca vão para *.

Rotação. Se uma chave vazar ou um site mudar de mãos, emitimos uma nova chave e a antiga para de funcionar imediatamente.

Testes antes do lançamento

Envie-nos o domínio de staging junto com o de produção, ou localhost:<port> para uma máquina de desenvolvimento. Ambos podem ficar na mesma chave.

Checklist

  1. Cliente envia nome, domínios, logo, cor, e-mail de reserva, os apps comprados (modo de IA ativado ou desativado) e o limite de cada app (e, opcionalmente, webhook, caminhos de página).
  2. Criamos a chave e enviamos os snippets.
  3. Cliente adiciona embed.js e os contêineres, primeiro em staging.
  4. Cliente verifica: busca → tracking, tarifas → detalhes → reserva (um e-mail de teste chega), um link compartilhado abre no site dele. Com uma CSP estrita, verifique no console do navegador se há navo24.com bloqueado.
  5. Cliente adiciona o domínio de produção (se ainda não estiver na lista) e publica.