# Premiers pas avec la Congestion API

> La Congestion API renvoie des indicateurs de congestion en temps réel pour un port — taux d'occupation, temps au port et navires au port — et facture un crédit par port pour lequel des données sont effectivement renvoyées.

La Congestion API de Safecube donne une vue en temps réel de l'activité d'un port. Pour tout port, identifié par son UN/LOCODE, elle renvoie trois familles d'indicateurs :

- **Taux d'occupation** — le niveau de remplissage du port, ventilé par type de navire (commercial, cargo, tanker, roro), avec l'écart à la moyenne historique ;
- **Temps au port** — des statistiques sur la durée de séjour des navires dans le port : minimum, médiane et maximum ;
- **Navires au port** — le nombre actuel de navires dans le port, par type.

Utilisez-la pour anticiper les retards, optimiser la planification des escales et alimenter les workflows de track and trace, d'ETA et de routage avec l'état de la congestion. La page [Couverture de la Congestion API](/fr/api/congestion/guides/coverage) liste les 205 ports couverts.

L'URL de base de la Congestion API est `https://api.sinay.ai/congestion/api/v1`.

## Authentification

Chaque requête à la Congestion API est authentifiée par votre clé d'API Safecube, envoyée dans l'en-tête `API_KEY`, avec les en-têtes HTTP standard. La clé d'API doit avoir accès au produit Congestion.

```http
GET /congestion/api/v1/congestion/FRLEH HTTP/1.1
Host: api.sinay.ai
API_KEY: <your API key>
```

Une requête dont la clé est absente, invalide ou expirée, ou dont la clé n'a pas accès au produit Congestion, est rejetée avec `401` ou `403` et ne consomme aucun crédit. La page [Authentification](/fr/api/getting-started/authentication) liste les en-têtes HTTP obligatoires.

## Endpoints

| Méthode | Endpoint                                                                                         | Description                                                    |
| ------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `GET`   | [`/congestion/{portCode}`](/fr/api/congestion/reference/retrieve-congestion-aggregate)            | Congestion agrégée d'un port                                   |
| `POST`  | [`/congestion/batch`](/fr/api/congestion/reference/retrieve-congestion-aggregate-batch)           | Congestion agrégée de 10 ports au plus en un seul appel        |
| `GET`   | [`/consumption/current-period`](/fr/api/congestion/reference/retrieve-current-consumption-period) | Crédits restants pour la période en cours                      |
| `GET`   | [`/consumption/periods`](/fr/api/congestion/reference/retrieve-consumption-periods)               | Historique complet de la consommation                          |

### Congestion d'un port

```http
GET /congestion/api/v1/congestion/FRLEH
API_KEY: <your API key>
```

### Congestion de plusieurs ports

`POST /congestion/batch` accepte jusqu'à 10 codes de port en un seul appel :

```http
POST /congestion/api/v1/congestion/batch
API_KEY: <your API key>
Content-Type: application/json

{ "portCodes": ["FRLEH", "NLRTM", "DEHAM"] }
```

La page de référence de chaque endpoint documente ses schémas complets de requête et de réponse.

## Décompte des crédits

L'accès à la Congestion API fonctionne par crédits, avec une règle : **un crédit est facturé par port pour lequel des données sont effectivement renvoyées.**

Chaque réponse indique sa facturation exacte dans trois en-têtes :

| En-tête de réponse  | Signification                                                             |
| ------------------- | ------------------------------------------------------------------------- |
| `X-Resource-Type`   | Type de ressource facturée : `PORT_CONGESTION`                            |
| `X-Requested-Count` | Nombre de ports demandés, doublons retirés                                |
| `X-Found-Count`     | Nombre de ports effectivement renvoyés — le nombre de crédits facturés    |

### Crédits pour un port

Un appel à `GET /congestion/{portCode}` coûte 1 crédit :

```text
X-Requested-Count: 1
X-Found-Count: 1      → 1 crédit facturé
```

### Crédits pour plusieurs ports

Pour `POST /congestion/batch` :

- `X-Requested-Count` est le nombre de ports uniques demandés : un port listé deux fois est compté une fois ;
- `X-Found-Count` est le nombre de ports pour lesquels des données ont effectivement été renvoyées, et le nombre de crédits facturés ;
- un port sans données est ignoré et n'est pas facturé.

Une requête batch sur 3 ports, dont l'un n'a aucune donnée disponible, est facturée 2 crédits :

```text
X-Requested-Count: 3
X-Found-Count: 2      → 2 crédits facturés, pas 3
```

### Requêtes gratuites

- Les requêtes en échec sont gratuites : les erreurs d'authentification, les codes de port mal formés et les réponses de quota dépassé ne consomment jamais de crédits.
- Les crédits de congestion sont un type de crédit dédié, indépendant des crédits des autres produits Safecube.

## Quotas et limite de requêtes

Deux protections indépendantes peuvent bloquer une requête à la Congestion API :

- **Quota de crédits atteint** — la requête reçoit la réponse `403 Forbidden`. Elle est bloquée avant traitement et ne consomme aucun crédit. Rechargez les crédits ou attendez la période suivante.
- **Trop de requêtes sur une courte fenêtre** — la requête reçoit la réponse `429 Too Many Requests`. La limite de requêtes est de 10 requêtes par 10 secondes et par clé d'API ; réessayez peu après.

La page [Limites de requêtes](/fr/api/getting-started/rate-limits) détaille la limite de requêtes commune à toutes les API Safecube.

## Suivre votre consommation

Pour consulter le solde de crédits sans consommer de crédit, appelez [`GET /consumption/current-period`](/fr/api/congestion/reference/retrieve-current-consumption-period) :

```http
GET /congestion/api/v1/consumption/current-period
API_KEY: <your API key>
```

| Champ                       | Signification                                |
| --------------------------- | -------------------------------------------- |
| `creditsInitial`            | Crédits alloués au début de la période       |
| `credits`                   | Crédits restants                             |
| `periodStart` / `periodEnd` | Début et fin de la période en cours          |
| `expired`                   | Indique si la période a expiré               |

[`GET /consumption/periods`](/fr/api/congestion/reference/retrieve-consumption-periods) renvoie l'historique complet des périodes de consommation.

## Cycle de vie d'une requête

1. Le client appelle la Congestion API avec son `API_KEY`.
2. La passerelle vérifie les droits d'accès et le solde de crédits de la clé. Quand le solde est insuffisant, la requête reçoit la réponse `403` et rien n'est facturé.
3. L'API récupère et agrège les données de congestion des ports demandés.
4. L'en-tête de réponse `X-Found-Count` indique combien de crédits ont été facturés.
5. Seuls les ports qui ont renvoyé des données sont facturés ; les ports sans données sont gratuits.

## Réponses d'erreur

Toutes les erreurs de la Congestion API partagent le même corps :

```json
{
  "errorCode": 404,
  "message": "unable to retrieve congestion",
  "details": [],
  "time": "2026-06-24T10:30:00Z"
}
```

| Statut                      | Signification                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `400 Bad Request`           | Entrée invalide, comme un code de port qui ne compte pas 5 caractères alphanumériques |
| `401 Unauthorized`          | Échec de l'authentification                                                          |
| `403 Forbidden`             | Limite d'utilisation atteinte                                                        |
| `404 Not Found`             | Aucune donnée de congestion trouvée pour la ressource demandée                       |
| `429 Too Many Requests`     | Limite de requêtes dépassée                                                          |
| `500 Internal Server Error` | Une erreur est survenue côté serveur                                                 |
