Safecube makes it easy to embed live container tracking into your own platform, customer portal, or internal tools using a simple iframe.

This guide will help you get started quickly and confidently.

✅ Why Use This?

📍 Display real-time shipment tracking inside your own interface
🔗 Use public sharing links – no login required
🧩 Offer a seamless branded experience with optional White Labeling

🧰 Prerequisites

Before you begin, ensure you have access to the required features:

Create a Safecube Account
Sign up at safecube.ai and retrieve your API key from your account.
Request Premium Feature Access
You must contact us to enable:
- ✅ Safecube Shipment Management API
- ✅ Iframe Embedding Authorization (we whitelist your domain)

👉 Request Access Here

🔁 Workflow Overview

Create a Shipment using the API
Retrieve the Public Sharing Link
Embed the Link into your app or site using an iframe

🛠️ Step-by-Step Guide

1. Create the Shipment

Make a request to:

POST https://api.sinay.ai/safecube/api/v1/public/shipments

Headers

API_KEY: your-api-key
Content-Type: application/json

Body Example

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

2. Get the Public Sharing Link

Use the following endpoint to retrieve the public link for embedding:

POST https://api.sinay.ai/safecube/api/v1/public/shipments/search

Headers

API_KEY: your-api-key
Content-Type: application/json

Body Example

{
  "shipmentNumbers": ["GCXU5630216"]
}

Sample Response

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

This is the URL you’ll embed inside your iframe.

3. Embed in Your Website or Tool

Now that you have the link, embed it using a standard HTML iframe:

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

💡You can adjust width/height and styling as needed.

🧩 Simplified Views: Embed Only What You Need

By default, the public link returned by the Shipment Management API embeds the full shipment tracking experience (including header and tabs).

However, if you prefer to embed only a specific part of the shipment data (like just the map or the event timeline), Safecube provides alternate views you can use — with the same token.

Just extract the token from the standard public URL and use one of the dedicated simplified view URLs below.

🔗 Example Base Public URL

This is the standard public link returned by the API: https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3

🎯 Alternative View URLs (just replace the token)

View Type	URL Format
Details View	`https://app.safecube.ai/iframe/shipment/details?token=YOUR_TOKEN`
Map Only	`https://app.safecube.ai/iframe/shipment/map?token=YOUR_TOKEN`
Event List Only	`https://app.safecube.ai/iframe/shipment/schedules?token=YOUR_TOKEN`

🧪 Regex Helper (for devs)

To convert the public link automatically to a simplified view, you can extract the token using a simple regex and build the new URL.

Here’s a JavaScript example:

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);
}

✅ Why Use Simplified Views?

Embed only what's relevant for your use case
Reduce visual clutter for users
Keep your interface clean and focused

These simplified views are ideal for integrations in dashboards, CRMs, or customer-facing portals where a full application-like UI is unnecessary.

Note: All views are still read-only and public — no login is required.

🧩 Bonus: Build a Shipment Lookup Widget

You can go beyond just displaying a shipment by building a simple input box where users enter their container or booking number. Behind the scenes, you’ll:

Use their input to call the Create Shipment endpoint.
Then fetch the Public Link.
Finally, embed the tracking view dynamically in an iframe.

🔧 Example Flow

User enters: GCXU5630216
You POST to /public/shipments with that number.
Then POST to /public/shipments/search to get the link.
Display the iframe with the returned public URL.

This gives your users the full tracking experience—without needing to sign in or contact support.

💡 Why This is Awesome

🕐 Saves time for your team and your users
🎯 Turns any page into a live tracking portal
🔒 Keeps everything secure and read-only via the public token

🔧 Full Self-Service Tracking Widget (Optional Advanced Integration)

If you want to go a step further, you can build a fully dynamic shipment tracking widget on your site.

This allows your users to enter their container, booking, or Bill of Lading number, and immediately see the Safecube tracking page — embedded right into your interface.

No logins, no external navigation — just instant tracking, fully integrated.

⚙️ How It Works

User enters their shipment number.
Your website calls Safecube’s API to:
- Create the shipment
- Fetch the public tracking link
You embed that link in an iframe, on the fly.

Here’s a ready-to-use HTML/JavaScript snippet that does all of this for you:

<!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"; // 🔐 Replace with your actual 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 searchRes = 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 searchRes.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 (err) {
        console.error(err);
        errorDiv.textContent = "An error occurred while tracking the shipment.";
      }
    }
  </script>

</body>
</html>

🎨 Optional: White Label Integration

You can further personalize the experience by replacing:

The Safecube subdomain (app.safecube.ai) with your own subdomain (yourbrand.safecube.ai)
The Safecube logo with your company logo

👉 This is part of our White Label Premium Feature.
Contact us to get it set up: Request Branding Access

🚀 You're All Set!

You’ve now embedded live container tracking into your own environment—with no login required and full flexibility.

Need help? Reach out to our team — we're happy to support you!