# Risque de surestaries

> La Container Tracking API détecte un risque de surestaries à partir des events du conteneur — le délai entre le gate in et le chargement au port de chargement, et entre le déchargement et le gate out au port de déchargement — comparé à un seuil.

Des frais de surestaries sont facturés quand un conteneur reste au port plus longtemps que le temps libre accordé par le transporteur ou l'autorité portuaire. Détecter le risque tôt permet au propriétaire de l'expédition d'adapter le planning et de payer moins de frais. Un seul appel à l'endpoint [`GET /shipment`](/fr/api/container-tracking/reference/get-shipment-detail) de la Container Tracking API renvoie les events de conteneur dont cette détection a besoin.

## Quand les frais de surestaries sont facturés

Des frais de surestaries peuvent être facturés dans deux situations :

- au port de chargement (POL), quand le conteneur est arrivé au terminal et n'a pas encore été chargé sur un navire ;
- au port de déchargement (POD), quand le conteneur a été déchargé du navire et n'a pas encore quitté le port.

## Logique de détection

Un risque de surestaries se détecte en mesurant, à chaque port, le délai entre deux events du conteneur, et en levant une alerte quand ce délai dépasse un seuil que vous choisissez.

| Port | Début du délai                                                         | Fin du délai                                                        | Repli quand un event manque                                      |
| ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| POL  | Arrivée du conteneur au terminal : statut `CGI` (gate in)              | Chargement du conteneur sur le navire : statut `CLL` (chargé)       | Départ du navire du POL (`VDL`) à la place du chargement         |
| POD  | Déchargement du conteneur du navire : statut `CDD` (déchargé)          | Départ du conteneur du port : statut `CGO` (gate out)               | Arrivée du navire au POD (`VAD`) à la place du déchargement      |

Appliquez-la aux events de chaque conteneur, dans `containers[].events` de la réponse :

1. Au POL, trouvez l'event de statut `CGI` et l'event de statut `CLL`. Quand l'event `CLL` manque, utilisez à la place la date de départ du navire.
2. Au POD, trouvez l'event de statut `CDD` et l'event de statut `CGO`. Quand l'event `CDD` manque, utilisez à la place la date d'arrivée du navire.
3. Calculez le délai entre les deux dates de chaque port.
4. Comparez chaque délai à votre seuil, et levez une alerte quand il est dépassé.
5. Quand l'event qui clôt le délai manque encore — le conteneur n'a pas été chargé, ou n'a pas quitté le port — le délai ne peut pas encore être calculé. Continuez à mettre à jour l'expédition : les compagnies maritimes ajoutent régulièrement des events.

::callout{type="info"}
Préférez toujours les events de chargement et de déchargement pour calculer le temps passé au port. N'utilisez les dates de départ et d'arrivée du navire que quand l'event de chargement ou de déchargement n'est pas disponible.
::

::callout{type="warning"}
La disponibilité de chaque event dépend de la compagnie maritime. La page [Codes de statut et d'event](/fr/api/container-tracking/guides/status-and-event-codes) montre quels events fournissent les principales compagnies maritimes.
::

## Exemple

La réponse ci-dessous, réduite aux events du conteneur, suit un conteneur chargé à Melbourne (`AUMEL`) et à destination de Colombo (`LKCMB`) :

```json
{
  "containers": [
    {
      "status": "IN_TRANSIT",
      "events": [
        {
          "location": { "name": "MELBOURNE", "locode": "AUMEL" },
          "description": "Gate in at Port terminal",
          "eventType": "EQUIPMENT",
          "eventCode": "GTIN",
          "status": "CGI",
          "date": "2024-05-29T07:34:00Z",
          "isActual": true
        },
        {
          "location": { "name": "MELBOURNE", "locode": "AUMEL" },
          "description": "Loaded on board",
          "eventType": "EQUIPMENT",
          "eventCode": "LOAD",
          "status": "CLL",
          "date": "2024-06-02T03:51:00Z",
          "isActual": true
        },
        {
          "location": { "name": "COLOMBO", "locode": "LKCMB" },
          "description": "Vessel Arrival",
          "eventType": "TRANSPORT",
          "eventCode": "ARRI",
          "status": "VAD",
          "date": "2024-07-06T13:30:00Z",
          "isActual": false
        }
      ]
    }
  ]
}
```

### Détection au port de chargement

- Le conteneur a à la fois un event `CGI` (gate in) et un event `CLL` (chargé) à Melbourne.
- La date du `CGI` est `2024-05-29T07:34:00Z`, celle du `CLL` est `2024-06-02T03:51:00Z`.
- Le temps passé au port de chargement est de **3 jours, 20 heures et 17 minutes**.

Comparez ce temps à votre seuil pour décider d'envoyer ou non une alerte.

### Détection au port de déchargement

- Le conteneur n'a qu'un event `VAD` (arrivée du navire) à Colombo, estimé, et aucun event `CGO` (gate out).
- Le risque de surestaries ne peut pas encore être calculé au port de déchargement.

Continuez à mettre à jour les données de cette expédition : la compagnie maritime ajoute des events au fil du voyage.

<!-- TODO: review by product team -->
