Skip to content

Événements & Commentaires

Cette page décrit, du point de vue d'un TMS intégrateur, le journal d'audit terrain (events/comments) — distinct du statut légal du document. Ni un événement, ni un commentaire, ne modifie jamais FreightDocument.status : ce sont des enregistrements informatifs et horodatés, complémentaires au cycle de vie du document.

Événements (events)

POST /v1/freightdocuments/{id}/events
GET  /v1/freightdocuments/{id}/events

Un événement capture une observation terrain : arrivée, départ, début/fin de chargement ou déchargement, cachet de contrôle, relevé de température.

{
  "event_type": "TEMPERATURE_CHECK",
  "transfer_type": "DELIVERY",
  "occurred_at": "2026-08-09T14:32:00Z",
  "geolocation": { "lat": 48.8566, "lng": 2.3522, "accuracy_meters": 8 },
  "value": { "temperature_celsius": -18.5 }
}

occurred_at vs recorded_at — point important pour toute intégration qui affiche ou trie ces événements : occurred_at est l'heure revendiquée par l'appareil du chauffeur au moment de l'observation, jamais vérifiable côté serveur. recorded_at (horodatage serveur à la réception, non modifiable par le client) est la seule référence chronologique légale — GET .../events trie toujours par recorded_at, jamais par occurred_at. Une horloge d'appareil désynchronisée n'inverse donc jamais l'ordre affiché.

Qui peut enregistrer un événement — permission RECORD_EVENT, accordée par défaut aux rôles physiquement présents lors d'un transfert : CARRIER, SUBSEQUENTCARRIER, PLACEOFTAKINGOVER, PLACEOFDELIVERY. Un CONSIGNOR/CONSIGNEE/SUBMITTER ne peut pas en créer par défaut.

Géolocalisation — geolocation est optionnelle ; si fournie, lat doit être entre -90 et 90, lng entre -180 et 180, sinon la requête est rejetée (event.invalid_geolocation).

Événements générés automatiquement — une signature HANDOVER/ACCEPTANCE réussie (relais transporteur-à-transporteur, voir Signature électronique) crée automatiquement un événement (HANDOVER_SIGNED/ACCEPTANCE_SIGNED), en plus de son propre enregistrement de preuve de signature — pour que la timeline events reste complète même pour les transferts qui ne changent jamais le statut légal du document.

Commentaires (comments)

POST /v1/freightdocuments/{id}/comments
GET  /v1/freightdocuments/{id}/comments

{ "comment_type": "IRREGULARITY", "text": "Sceau brisé à l'arrivée, marchandise inspectée." }

Trois types : INFO, WARNING, IRREGULARITY. Tout rôle ayant accès au document peut commenter (permission COMMENT, accordée par défaut depuis le début de cette API).

signature_id (nullable) — un commentaire peut être lié à la signature exacte pendant laquelle il a été capturé, quand il provient du champ comment_text optionnel soumis avec la complétion d'une signature (voir Signature électronique) plutôt que de POST .../comments. Un commentaire créé ainsi est toujours de type INFO. signature_id est null pour tout commentaire créé via POST .../comments directement. Une photo prise au même moment est liée de la même façon, mais côté pièces jointes : voir signature_id dans Pièces jointes & PDF.

Déclenchement webhook

Un commentaire WARNING ou IRREGULARITY déclenche une livraison webhook vers vos souscriptions de type COMMENT sur ce document (voir Webhooks) — un commentaire INFO n'en déclenche jamais. Le payload reprend exactement la même structure que les événements STATUS, avec un objet comment en plus :

{
  "event_id": "b6e6c8b2-...-9f0a1c2d3e4f",
  "event_type": "COMMENT",
  "occurred_at": "2026-08-09T14:35:00Z",
  "from_status": null,
  "to_status": null,
  "comment": {
    "id": "7f3e...-comment-id",
    "comment_type": "WARNING",
    "text": "Pallet damaged in transit.",
    "created_at": "2026-08-09T14:35:00Z"
  },
  "freight_document": { "...": "identique à GET /v1/freightdocuments/{id}" }
}

Comme pour les événements STATUS, freight_document est rendu exactement comme si votre compte appelait lui-même GET /v1/freightdocuments/{id} — même scoping par permissions, même principe de visibilité de chaîne. Souscrivez séparément à STATUS et COMMENT : une souscription à l'un ne reçoit jamais les livraisons de l'autre.