Présentation de l'API
Safecube expose ses données de suivi de conteneurs maritimes à travers cinq API REST. Chaque API a sa propre URL de base et son propre numéro de version, et toutes s'authentifient avec la même clé d'API Safecube, envoyée dans l'en-tête API_KEY.
API disponibles
| API | Ce qu'elle fait | URL de base | Version |
|---|---|---|---|
| Container Tracking | Suit n'importe quel conteneur à partir d'un numéro de conteneur, de connaissement ou de booking, sur plus de 170 compagnies maritimes, à travers un seul endpoint. | https://api.sinay.ai/container-tracking/api/v2 | 2.8.0 |
| Webhooks | Envoie des events de webhook vers vos propres endpoints dès que de nouvelles données de suivi sont disponibles pour vos expéditions, sans interroger la Container Tracking API. | https://api.sinay.ai/webhook/api/v1 | 1.2.1 |
| Shipment Management | Crée, supprime et recherche les expéditions de votre espace de travail de l'application web Safecube. | https://api.sinay.ai/safecube/api/v1 | 1.0.0 |
| Ports Intelligence | Renvoie le détail d'un port, l'occupation de ses postes à quai et les navires présents au port. | https://api.sinay.ai/ports-intelligence/api/v1 | 1.0.0-beta |
| Congestion | Renvoie la congestion d'un port et permet de suivre votre consommation de crédits. | https://api.sinay.ai/congestion/api/v1 | 1.1.1 |
Toutes les API Safecube sont servies depuis l'hôte api.sinay.ai, en HTTPS. Le chemin d'un endpoint documenté dans la référence s'ajoute à l'URL de base de son API : l'endpoint GET /shipment de la Container Tracking API s'appelle à l'adresse https://api.sinay.ai/container-tracking/api/v2/shipment.
Versionnement
Chaque API Safecube est versionnée par un seul numéro majeur, qui fait partie de son URL de base : v2 dans /container-tracking/api/v2, v1 dans /webhook/api/v1. De nouvelles fonctionnalités peuvent arriver dans la même version majeure tant qu'elles n'introduisent aucun changement incompatible : une intégration construite sur v2 continue donc de fonctionner quand la Container Tracking API passe de 2.8.0 à une version 2.x ultérieure.
Le numéro de version complet du tableau, 2.8.0 ou 1.2.1, identifie la version actuellement publiée. Il est purement indicatif : il n'apparaît jamais dans l'URL et une requête ne peut pas le choisir.
Authentification et limites
La même clé d'API authentifie toutes les API Safecube. Elle est envoyée dans un en-tête nommé API_KEY avec chaque requête, et elle se trouve dans l'application web Safecube sous Developers > API Credentials. La Ports Intelligence API exige en plus que la clé ait reçu un accès à cette API.
Chaque clé d'API est limitée à 10 requêtes par tranche de 10 secondes. Une requête au-delà de ce rythme reçoit la réponse 429 Too Many Requests.
Exemple de requête
La requête ci-dessous demande à la Container Tracking API les données de suivi de ZZZZ0000000, une expédition de test qui ne coûte rien à interroger et renvoie un voyage complet du Havre à Rotterdam. Remplacez $SAFECUBE_API_KEY par votre clé d'API.
curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000&shipmentType=CT" \
-H "API_KEY: $SAFECUBE_API_KEY"