Intégrer une expédition dans une iframe
Le suivi d'expédition Safecube peut être intégré en direct dans votre propre plateforme, votre portail client ou vos outils internes avec une iframe HTML standard. La page intégrée est le lien de partage public de l'expédition, renvoyé par la Shipment Management API : elle ne demande aucune connexion, et son habillage peut être remplacé par le vôtre grâce à l'option marque blanche.
Prérequis
- Un compte Safecube et une clé d'API — inscrivez-vous sur safecube.ai et récupérez votre clé d'API dans l'application web Safecube, sous Developers > API Credentials.
- L'autorisation d'intégration en iframe — l'intégration en iframe fait partie du pack marque blanche et s'active sur demande, car Safecube doit autoriser le domaine des pages qui intègrent l'iframe. Demandez-la à l'équipe Safecube, en indiquant ce domaine. La Shipment Management API elle-même est incluse dans tous les plans Safecube et ne demande aucune démarche.
Déroulé
- Créez l'expédition avec la Shipment Management API.
- Récupérez son lien de partage public.
- Intégrez le lien dans votre application ou votre site web avec une
iframe.
Étape 1 : créer l'expédition
Appelez POST /public/shipments avec le numéro d'expédition et, en option, le code SCAC de la compagnie maritime :
POST https://api.sinay.ai/safecube/api/v1/public/shipments
API_KEY: <your API key>
Content-Type: application/json
{
"shipments": [
{
"shipmentNumber": "GCXU5630216",
"sealine": "COSU"
}
]
}
Étape 2 : obtenir le lien de partage public
Appelez POST /public/shipments/search avec le numéro d'expédition :
POST https://api.sinay.ai/safecube/api/v1/public/shipments/search
API_KEY: <your API key>
Content-Type: application/json
{
"shipmentNumbers": ["GCXU5630216"]
}
Le champ link de chaque résultat est le lien de partage public, l'URL à intégrer dans l'iframe :
{
"results": [
{
"shipmentNumber": "GCXU5630216",
"link": "https://app.safecube.ai/shared/shipment?token=abc123..."
}
]
}
Étape 3 : intégrer le lien
Intégrez le lien de partage public avec une iframe HTML standard, et ajustez sa largeur, sa hauteur et son style à votre mise en page :
<iframe
src="https://app.safecube.ai/shared/shipment?token=abc123..."
width="100%"
height="600"
style="border: none;"
allowfullscreen
></iframe>
Vues simplifiées
Par défaut, le lien de partage public intègre la page complète de suivi de l'expédition, en-tête et onglets compris. Pour n'en intégrer qu'une partie — la carte ou la chronologie des events — utilisez l'une des vues simplifiées, avec le même token que le lien de partage public.
Un lien de partage public a la forme https://app.safecube.ai/shared/shipment?token=3beaacdd-7bc7-44f9-a349-b99a85abb4e3. Extrayez son token et construisez l'URL de la vue dont vous avez besoin :
| Vue | URL |
|---|---|
| Vue détails | https://app.safecube.ai/iframe/shipment/details?token=YOUR_TOKEN |
| Carte seule | https://app.safecube.ai/iframe/shipment/map?token=YOUR_TOKEN |
| Liste des events seule | https://app.safecube.ai/iframe/shipment/schedules?token=YOUR_TOKEN |
Ce JavaScript extrait le token d'un lien de partage public et construit les URL des trois vues simplifiées :
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)
}
Les vues simplifiées n'intègrent que ce qui sert votre cas d'usage et gardent votre interface épurée. Elles conviennent aux tableaux de bord, aux CRM et aux portails clients, où une interface complète d'application est superflue. Chaque vue, complète ou simplifiée, est publique et en lecture seule : aucune connexion n'est demandée.
Widget de suivi en libre-service
Les trois étapes se combinent en un widget de suivi : vos utilisateurs saisissent un numéro de conteneur, de booking ou de connaissement sur votre site, et la page de suivi Safecube s'affiche intégrée à votre interface, sans connexion et sans quitter votre site.
- L'utilisateur saisit un numéro d'expédition, comme
GCXU5630216. - Votre site web appelle
POST /public/shipmentspour créer l'expédition. - Votre site web appelle
POST /public/shipments/searchpour récupérer son lien de partage public. - Votre site web affiche le lien de partage public dans une
iframe.
La page HTML et JavaScript ci-dessous implémente le 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 {
// Étape 1 : créer l'expédition
await fetch(`${API_BASE}/public/shipments`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', API_KEY: API_KEY },
body: JSON.stringify({ shipments: [{ shipmentNumber }] }),
})
// Étape 2 : rechercher le lien public
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>
Marque blanche
Le suivi intégré peut porter votre marque au lieu de celle de Safecube :
- votre propre sous-domaine, comme
yourbrand.safecube.ai, remplaceapp.safecube.ai; - le logo de votre entreprise remplace le logo Safecube.
La marque blanche est une fonctionnalité premium : demandez-la à l'équipe Safecube.