# Présentation de l'API

> Safecube expose cinq API REST, Container Tracking, Webhooks, Shipment Management, Ports Intelligence et Congestion, chacune avec sa propre URL de base et sa propre version, toutes authentifiées avec la même clé d'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`.

::callout{type="warning"}
La Ports Intelligence API est en bêta. Elle peut évoluer et n'est pas forcément tout à fait stable : utilisez-la avec prudence en production.
::

## 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.

```bash
curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000&shipmentType=CT" \
  -H "API_KEY: $SAFECUBE_API_KEY"
```
