Skip to content
Navo24Navo24

Guías

Integrar las apps de Navo en el sitio de un cliente

Inserta seguimiento de contenedores en tu web, tarifas, itinerarios marítimos y modo IA, con tu marca, una etiqueta script y clave bloqueada por dominio.

Puedes incrustar el seguimiento de contenedores en el sitio web propio de un cliente, junto con tarifas de flete e itinerarios marítimos. Son las mismas apps que ves en el sitio de ejemplo de un transitario: un widget de búsqueda para la página de inicio y una página completa para cada app. Cada una se muestra con el nombre, el logo y el color del cliente. Cada vista tiene su propio enlace, de modo que un visitante puede enviar a un compañero un contenedor, una búsqueda de tarifa, una tarifa, una salida, un buque o un puerto, y se abre en el sitio del cliente.

No se necesita ninguna clave API ni servidor en el lado del cliente. La clave de incrustación es pública y solo funciona en los dominios que indiquemos para ella.

Qué nos envía el cliente

ElementoEjemploObligatorio
Nombre de la empresa tal como deben verlo los visitantesAcme LogisticsSí
Dominios donde se ejecutarán las apps (producción, staging)acme.com, www.acme.com, staging.acme.comSí
Logo, SVG o PNG, marca cuadrada u horizontalhttps://acme.com/logo.svgSí
Color de marca, un valor hex#0e6ba8Sí
Más colores, fuentes, redondeo de esquinasver AparienciaOpcional
E-mail que recibe las solicitudes de reserva[email protected]Para tarifas de flete
URL de webhook para solicitudes de reserva (a su CRM/TMS)https://acme.com/hooks/navoOpcional
Qué apps quierecualquiera de tracking, freight, schedules; modo AI activado o desactivadoSí
Límite de uso por app, al mes o al añotracking: 300 envíos únicos al mesSí
Páginas donde vivirá cada app/track, /rates, /schedulesRecomendado
“Con tecnología de Navo” mostrado u ocultomostradoPredeterminado: mostrado

Creamos la clave y devolvemos los snippets de abajo, con la clave ya incluida.

Qué puede incluir una clave

Una clave abre una app o varias, y el modo AI es un interruptor aparte:

PaqueteApps en la claveQué obtiene el visitante
Solo trackingtrackingPágina de tracking; el widget de búsqueda muestra la caja de tracking sin pestañas y sin interruptor de AI
Tracking con AItracking, aiLo mismo, más modo AI en el widget de búsqueda y “Preguntar a AI” en los envíos
Tarifas e itinerariosfreight, schedulesDos pestañas en el widget de búsqueda, las páginas de tarifas e itinerarios
Todotracking, freight, schedules, aiLas tres pestañas, modo AI, todas las páginas

El widget se construye a partir de la clave: una pestaña, una página o un botón de AI que la clave no abre no se dibuja en absoluto, y nuestro servidor rechaza sus datos aunque alguien fuerce la solicitud.

Límites de uso

Cada app de una clave tiene su propio límite, por mes natural o por año natural (UTC). Qué cuenta como una unidad:

AppUna unidadRepeticiones gratuitas
trackingUn envío único (contenedor, reserva o número B/L)El mismo envío durante el resto del periodo
freightUna búsqueda de tarifa (ruta y equipo)La misma búsqueda el mismo día
schedulesUna búsqueda de itinerario (ruta, buque o puerto)La misma búsqueda el mismo día
aiUna pregunta al asistente de AINinguna

Ejemplo: tracking con 300 envíos únicos al mes. Los visitantes del cliente pueden abrir y refrescar esos 300 envíos tantas veces como quieran durante todo el mes; el envío 301 se rechaza hasta el día 1 del mes siguiente. Cuando una app alcanza su límite, los visitantes ven “Este servicio está pausado en este sitio por ahora. Ponte en contacto con .” Las demás apps de la clave siguen funcionando. Vemos el uso por app y podemos aumentar un límite en cualquier momento, sin cambios en el sitio del cliente.

Instalación

Pon el loader una vez en cada página que muestre una app:

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

Después, un contenedor donde deba aparecer la app.

Widget de búsqueda (hero de la página de inicio, o cualquier página). Una caja con una pestaña por cada app de la clave (tracking, tarifas, itinerarios) y modo AI si la clave lo incluye. Con una sola app no hay pestañas:

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

Con data-navo-pages, el widget envía a los visitantes a las páginas propias del cliente. Sin él, el resultado se abre dentro del propio frame del widget.

Página de tracking (/track):

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

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

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

Página de itinerarios marítimos (/schedules), con tres pestañas: por ruta, por buque, por puerto:

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

Usa el mismo valor de data-navo-pages en cada app para que los enlaces cruzados (por ejemplo “Mostrar tarifas” en una salida, o “Itinerario del buque” en un envío) aterricen en la página correcta del sitio del cliente.

Opciones

AtributoQué hace
data-navo-appsearch, tracking, freight o schedules.
data-navo-keyLa clave de incrustación del sitio.
data-navo-pagesMapa JSON de app a ruta de página en el sitio del cliente.
data-navo-heightAltura fija en px. Por defecto, el frame crece con su contenido; tracking es un mapa completo, 680 px.
data-navo-syncoff mantiene la URL de la página sin cambios mientras el visitante navega.
data-navo-themeJSON con colores, fuentes y esquinas, ver Apariencia.

Sitios con una Content Security Policy

Si el sitio envía una cabecera Content-Security-Policy (o una <meta http-equiv>) con script-src o frame-src, añade navo24.com a ambas, de lo contrario el navegador bloquea el loader o el frame y el contenedor queda vacío:

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

Con child-src en lugar de frame-src, añádelo ahí. No hace falta nada más: las apps cargan sus datos, fuentes y mapas dentro del frame, bajo nuestra propia política. La consola del navegador indica la directiva bloqueada si falta alguna.

Eventos para analítica y CRM

El contenedor dispara eventos DOM cuando un visitante hace algo, para que el sitio pueda enviarlos a Google Analytics, a un gestor de etiquetas o a su CRM. Hacen bubble, así que un único listener en document captura todas las apps de la página.

EventoCuándoevent.detail
navo:searchUna búsqueda devolvió resultadosapp (tracking, freight, schedules) y la consulta: ref, o origin, destination, container
navo:bookingSe envió una solicitud de reservareference, origin, destination, container, quantity, carrier, price, currency
navo:limitUn límite detuvo una búsquedaapp, code (por ejemplo 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>

Los datos de contacto del visitante no van en los eventos: solo se envían al e-mail de reservas y al webhook.

Apariencia

Por defecto, las apps toman el color de marca del cliente desde la clave. Para ajustarlas mejor al sitio, añade data-navo-theme al contenedor: colores, fuentes, redondeo de esquinas y modo oscuro.

<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 las claves son opcionales. Un valor que no sea válido se ignora, el resto sigue aplicándose.

ClaveQué cambiaEjemplo
accentBotones, enlaces, pestañas activas, interruptores, anillo de foco. Los tonos hover y pulsado se calculan a partir de él"#e4002b"
textTexto principal"#1a1a1a"
mutedTexto secundario: etiquetas, ayudas, fechas"#6b7280"
headingEncabezados, nombres de navieras y buques, líneas de mapa"#002f6c"
backgroundFondo de página de la app. "transparent" deja ver el fondo propio del cliente"#ffffff"
surfaceTarjetas, inputs, franjas de tabla"#f5f7fa"
borderBordes y separadores"#e5e7eb"
successEstados positivos: entregado, puntual, más barato"#15803d"
radiusRedondeo de esquinas de tarjetas y paneles, px (0 a 40)8
buttonRadiusRedondeo de esquinas de botones e inputs, px. 999 crea píldoras (el valor predeterminado)6
fontFuente del cuerpo. Cualquier familia de Google Fonts se carga por ti; "system" usa la fuente del sistema del visitante"Inter"
headingFontFuente para encabezados, mismas reglas. Sin ella, los encabezados usan font"Playfair Display"
fontCssTu propia hoja de estilos de fuentes (URL https:// con reglas @font-face), para fuentes que no están en Google Fonts. Entonces font y headingFont nombran familias de ese archivo"https://acme.com/fonts/brand.css"
mode"dark" para sitios con diseño oscuro"dark"

Los colores son hex: #rgb, #rrggbb o #rrggbbaa.

Puntos de partida listos para usar:

<!-- 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"}'

Un tema para todas las páginas. También podemos guardar el tema en la clave. Entonces todos los contenedores de todas las páginas lo reciben sin el atributo, y podemos ajustarlo después sin cambios en el sitio del cliente. data-navo-theme en un contenedor sigue teniendo prioridad sobre el tema de la clave, clave por clave.

El tema solo llega a la app dentro del frame: nunca cambia la propia página del cliente.

React y Next.js, con indexación de búsqueda

Usa esto cuando el sitio del cliente esté creado con React o Next.js y el contenido de la app deba indexarse como página del cliente (por ejemplo, una página por ruta, “itinerario marítimo de Shanghai a Hamburg”).

Consta de dos partes:

  1. Snapshot. El servidor del cliente obtiene de nosotros los datos de la ruta como HTML plano (tabla de itinerarios o tabla de tarifas, un encabezado, un resumen de una línea y marcado schema.org) y los pone en su propia página. Los motores de búsqueda lo indexan como contenido del cliente, en la URL del cliente.
  2. App. En el navegador, la app interactiva se monta encima, con búsqueda, filtros, detalles y reserva. El snapshot permanece en la página como una tabla plegable bajo la app, de modo que crawlers y visitantes ven el mismo contenido.

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

Sin format=html, la respuesta es 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"
  }
}

Usa title y description para el <title> de la página y la meta description, html para el cuerpo. La respuesta puede cachearse durante 30 minutos (Cache-Control: max-age=1800). Un snapshot cuenta como una búsqueda contra el límite de la app; la misma ruta el mismo día es gratis. Tracking no tiene snapshot: los envíos son privados para el 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>
      )}
    </>
  );
}

Cómo lo ve un motor de búsqueda: el título y la descripción propios de la página, un encabezado y una tabla completa de salidas (o tarifas) en el HTML, con marcado Dataset. Cómo lo ve un visitante: la app en vivo, ya abierta en esa ruta, con los mismos resultados como tabla plegada debajo. Los visitantes sin JavaScript ven la tabla abierta. La tabla está plegada, no oculta, así que la página no muestra a los crawlers nada que un visitante no pueda abrir.

El HTML del snapshot viene de nuestro servidor con todos los valores escapados, así que es seguro insertarlo. Dale estilo con las clases .navo-snapshot y .navo-snapshot-table si alguna vez se muestra.

Otros frameworks de servidor (Remix, Astro, Nuxt, PHP, WordPress) funcionan igual: obtén el snapshot en el servidor, imprime html en la página y pon el contenedor junto a él.

React sencillo (sin renderizado de servidor)

Cuando la indexación de búsqueda no importa (una página de tracking detrás de un menú, una intranet), el componente sin snapshot es suficiente:

El loader funciona igual en una aplicación de una sola página (React, Vue, Svelte): renderiza el contenedor y después llama a 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' }} />

En Next.js, ponlo en un componente cliente ('use client').

Por qué un frame

El loader dibuja cada app dentro de un frame desde navo24.com. Así funcionan Stripe Checkout, los embeds de Google Maps y los reproductores de YouTube, por las mismas razones:

  • Bloqueo por dominio. El propio navegador se niega a mostrar la app en un sitio que no esté en la lista de la clave (frame-ancestors). Un componente de script cargado en la página del cliente no puede bloquearse de esta forma.
  • Sin conflictos de estilos. El CSS del cliente no puede romper la app y nuestro CSS no puede tocar su sitio.
  • Actualizaciones sin el cliente. Nuevas navieras, correcciones y funciones llegan a todos los sitios el mismo día; no hay nada que actualizar en el lado del cliente.
  • Motores de búsqueda. El contenido dentro de un frame no se indexa como página del cliente, igual que con cualquier embed de mapa o vídeo. Cuando eso importe, añade el snapshot renderizado en servidor, ver React y Next.js, con indexación de búsqueda.

Los visitantes no inician sesión dentro del frame, así que el bloqueo de cookies de terceros por parte del navegador no le afecta.

Enlaces a una vista exacta

Mientras un visitante trabaja en una app, la URL de la página le sigue: ?navo_app=<app>&navo=<view>. Los botones Copiar enlace dentro de las apps producen el mismo tipo de enlace. Ejemplos en una página de cliente /rates:

VistaEnlace
Un contenedor/track?navo_app=tracking&navo=ref%3DZMOU8956106
Búsqueda de tarifa en una ruta/rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC
Una tarifala búsqueda anterior más %26quote%3D<id>
Búsqueda de itinerario en una ruta/schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM
Una salidala búsqueda anterior más %26sailing%3D<id>
Un buque/schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890
Un puerto/schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN

Una tarifa o salida compartida sigue abriéndose después de haber salido de los resultados en vivo; se muestra con la fecha en que se tomaron sus datos.

Solicitudes de reserva

Reservar en una tarifa abre un formulario de solicitud (contacto, empresa, e-mail, teléfono, número de contenedores, fecha de carga lista, carga, notas). Al enviarlo:

  • se envía un e-mail a la dirección de reservas del cliente, con la ruta, el equipo, la naviera, el precio que vio el visitante y los datos de contacto del visitante. Reply-To es el visitante, así que el cliente responde directamente desde su buzón;
  • si hay un webhook configurado, se envía la misma solicitud por POST 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" }
  }
}

El visitante ve una confirmación con la referencia. No se cobra nada y no se hace ninguna reserva con la naviera: el cliente confirma espacio y responde.

Sin e-mail de reservas ni webhook, el formulario queda como demo y lo indica.

Qué ven los visitantes y qué no ven

  • Nombres y logos de navieras, precios, tiempos de tránsito, validez y qué incluye una tarifa.
  • Las tarifas sin naviera nombrada se muestran como “Selección de ”, con el logo del cliente.
  • Las fuentes y plataformas de tarifas no se muestran nunca. Se eliminan en nuestro servidor antes de que los datos lleguen al navegador.

Seguridad

Bloqueo por dominio. Las páginas de la app responden con Content-Security-Policy: frame-ancestors listando solo los dominios de la clave, así que un navegador se niega a mostrarlas en cualquier otro lugar. Las solicitudes de datos llevan la clave y el host de la página padre, y se rechazan cuando el host no está en la lista. Una clave copiada en otro sitio no funciona allí.

Límites. Cada app de una clave tiene su propio límite mensual o anual (ver Límites de uso). Además, cada clave tiene un tope de seguridad de 50,000 solicitudes al mes, un techo de 600 solicitudes por minuto para todo el sitio (para que un pico de tráfico de un sitio no ralentice las apps de otros; se aumenta bajo petición) y límites por visitante contra abuso automatizado; por encima de ellos, la app muestra un breve mensaje de “inténtalo de nuevo” y dispara navo:limit.

Mensajes. El frame y el loader se comunican mediante postMessage, y cada lado envía solo al origen exacto del otro: el frame a la página del cliente, el loader a navo24.com. Los detalles de búsqueda nunca se envían a *.

Rotación. Si una clave se filtra o un sitio cambia de manos, emitimos una clave nueva y la antigua deja de funcionar al instante.

Pruebas antes del lanzamiento

Envíanos el dominio de staging junto con el de producción, o localhost:<port> para una máquina de desarrollo. Ambos pueden estar en la misma clave.

Checklist

  1. El cliente envía nombre, dominios, logo, color, e-mail de reservas, las apps que compró (modo AI activado o desactivado) y el límite de cada app (y, opcionalmente, webhook y rutas de página).
  2. Creamos la clave y enviamos los snippets.
  3. El cliente añade embed.js y los contenedores, primero en staging.
  4. El cliente comprueba: búsqueda → tracking, tarifas → detalles → reserva (llega un e-mail de prueba), un enlace compartido se abre en su sitio. Con una CSP estricta, revisa la consola del navegador por navo24.com bloqueado.
  5. El cliente añade el dominio de producción (si aún no está en la lista) y sale a producción.