# Embed a shipment in an iframe

> The public sharing link returned by the Shipment Management API embeds live, read-only Safecube shipment tracking in your own platform as an iframe, with no login, in a full view or a details, map or event list view.

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](https://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](https://app.safecube.ai/contact?topic=premium_feature), 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`](/en/api/shipment-management/reference/create-shipments) with the shipment number and, optionally, the SCAC code of the shipping line:

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

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

## Step 2: get the public sharing link

Call [`POST /public/shipments/search`](/en/api/shipment-management/reference/search-shipments) with the shipment number:

```http
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:

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

## Step 3: embed the link

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

```html
<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:

| View            | URL                                                                  |
| --------------- | -------------------------------------------------------------------- |
| 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` |

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

```js
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:

```html
<!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>
```

::callout{type="danger"}
This page sends your API key from the browser of every visitor, where anyone can read it. Run the two API calls on your own server instead, and send only the public sharing link to the browser.
::

## 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](https://app.safecube.ai/contact?topic=premium_feature).
