Skip to content
Documentation sections

Embed a shipment in an iframe

Safecube shipment tracking can be embedded live in your own platform, customer portal or internal tools with a standard HTML iframe. The embedded page is the public sharing link of the shipment, returned by the Shipment Management API: it requires no login, and its branding can be replaced with yours through the white label option.

Prerequisites

  1. A Safecube account and API key — sign up at safecube.ai and retrieve your API key in the Safecube web application, under Developers > API Credentials.
  2. Iframe embedding authorization — iframe embedding is part of the white label pack and is enabled on request, because Safecube must authorize the domain of the pages that embed the iframe. Request it from the Safecube team, with that domain. The Shipment Management API itself is included in every Safecube plan and needs no request.

Workflow

  1. Create the shipment with the Shipment Management API.
  2. Retrieve its public sharing link.
  3. Embed the link in your application or website with an iframe.

Step 1: create the shipment

Call POST /public/shipments with the shipment number and, optionally, the SCAC code of the shipping line:

POST https://api.sinay.ai/safecube/api/v1/public/shipments
API_KEY: <your API key>
Content-Type: application/json

{
  "shipments": [
    {
      "shipmentNumber": "GCXU5630216",
      "sealine": "COSU"
    }
  ]
}

Call POST /public/shipments/search with the shipment number:

POST https://api.sinay.ai/safecube/api/v1/public/shipments/search
API_KEY: <your API key>
Content-Type: application/json

{
  "shipmentNumbers": ["GCXU5630216"]
}

The link field of each result is the public sharing link, the URL to embed in the iframe:

{
  "results": [
    {
      "shipmentNumber": "GCXU5630216",
      "link": "https://app.safecube.ai/shared/shipment?token=abc123..."
    }
  ]
}

Embed the public sharing link with a standard HTML iframe, and adjust its width, height and style to your layout:

<iframe
  src="https://app.safecube.ai/shared/shipment?token=abc123..."
  width="100%"
  height="600"
  style="border: none;"
  allowfullscreen
></iframe>

Simplified views

By default, the public sharing link embeds the full shipment tracking page, header and tabs included. To embed only part of it — the map or the event timeline — use one of the simplified views, with the same token as the public sharing link.

A public sharing link has the form https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3. Extract its token and build the URL of the view you need:

ViewURL
Details viewhttps://app.safecube.ai/iframe/shipment/details?token=YOUR_TOKEN
Map onlyhttps://app.safecube.ai/iframe/shipment/map?token=YOUR_TOKEN
Event list onlyhttps://app.safecube.ai/iframe/shipment/schedules?token=YOUR_TOKEN

This JavaScript extracts the token from a public sharing link and builds the three simplified view URLs:

const publicLink = 'https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3'
const tokenMatch = publicLink.match(/token=([a-f0-9-]+)/)

if (tokenMatch) {
  const token = tokenMatch[1]
  const mapViewUrl = `https://app.safecube.ai/iframe/shipment/map?token=${token}`
  const detailsViewUrl = `https://app.safecube.ai/iframe/shipment/details?token=${token}`
  const scheduleViewUrl = `https://app.safecube.ai/iframe/shipment/schedules?token=${token}`

  console.log('Map view:', mapViewUrl)
  console.log('Details view:', detailsViewUrl)
  console.log('Schedule view:', scheduleViewUrl)
}

Simplified views embed only what is relevant to your use case and keep your interface free of clutter. They suit dashboards, CRMs and customer-facing portals, where a full application-like interface is unnecessary. Every view, full or simplified, is read-only and public: no login is required.

Self-service tracking widget

The three steps combine into a tracking widget: your users enter a container, booking or bill of lading number on your site, and the Safecube tracking page appears embedded in your interface, with no login and no navigation away.

  1. The user enters a shipment number, such as GCXU5630216.
  2. Your website calls POST /public/shipments to create the shipment.
  3. Your website calls POST /public/shipments/search to retrieve its public sharing link.
  4. Your website displays the public sharing link in an iframe.

The HTML and JavaScript page below implements the widget:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Track Your Shipment</title>
    <style>
      body { font-family: sans-serif; padding: 2rem; }
      input, button { padding: 0.5rem; margin-right: 0.5rem; }
      iframe { width: 100%; height: 600px; margin-top: 2rem; border: 1px solid #ccc; }
    </style>
  </head>
  <body>
    <h1>Track Your Shipment</h1>
    <p>Enter your container, booking, or BL number:</p>
    <input type="text" id="shipmentNumber" placeholder="e.g. GCXU5630216" />
    <button onclick="trackShipment()">Track</button>

    <div id="error" style="color: red; margin-top: 1rem;"></div>
    <iframe id="trackingIframe" style="display: none;"></iframe>

    <script>
      const API_KEY = 'your-api-key'
      const API_BASE = 'https://api.sinay.ai/safecube/api/v1'

      async function trackShipment() {
        const shipmentNumber = document.getElementById('shipmentNumber').value.trim()
        const errorDiv = document.getElementById('error')
        const iframe = document.getElementById('trackingIframe')
        errorDiv.textContent = ''
        iframe.style.display = 'none'

        if (!shipmentNumber) {
          errorDiv.textContent = 'Please enter a shipment number.'
          return
        }

        try {
          // Step 1: create the shipment
          await fetch(`${API_BASE}/public/shipments`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json', API_KEY: API_KEY },
            body: JSON.stringify({ shipments: [{ shipmentNumber }] }),
          })

          // Step 2: search for the public link
          const searchResponse = await fetch(`${API_BASE}/public/shipments/search`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json', API_KEY: API_KEY },
            body: JSON.stringify({ shipmentNumbers: [shipmentNumber] }),
          })

          const data = await searchResponse.json()
          if (data.results && data.results.length > 0 && data.results[0].link) {
            iframe.src = data.results[0].link
            iframe.style.display = 'block'
          } else {
            errorDiv.textContent = 'Shipment created, but no link found. Try again shortly.'
          }
        } catch (error) {
          console.error(error)
          errorDiv.textContent = 'An error occurred while tracking the shipment.'
        }
      }
    </script>
  </body>
</html>

White label

The embedded tracking can carry your brand instead of Safecube's:

  • your own subdomain, such as yourbrand.safecube.ai, replaces app.safecube.ai;
  • your company logo replaces the Safecube logo.

White label is a premium feature: request it from the Safecube team.