Skip to content

Cycle de vie d'un DeCa

Chaque DeCa renvoyé par l'API porte un champ status : l'étape où il en est, une seule valeur à la fois. Votre TMS n'a pas à la déduire des dates du document. Elle est calculée à chaque lecture, à partir de ce qui s'est réellement passé.

Les statuts

                 ┌──── assigné à votre chauffeur ─────────────────┐
                 │                                                ▼
  draft ─────────┤                                             issued ──▶ finished
                 │                                                ▲
                 └── confié au sous-traitant ─▶ awaiting_vehicle ─┘
                     (envoi ou lien d'accès)      (camion déclaré)

  issued / awaiting_vehicle ──▶ deletion_requested ──▶ deleted
  issued ──▶ superseded   (remplacé par un nouveau document)
status Ce que ça veut dire Facturé ? PDF ?
draft Créé, jamais assigné, ni envoyé, ni confié par lien. non non
awaiting_vehicle Confié à un sous-traitant (envoyé à son compte Fincargo, ou lien d'accès généré), dont le camion n'est pas encore déclaré. oui pas encore
issued Le PDF existe ; le transport n'est pas déclaré terminé. oui oui
finished Le transport est déclaré terminé. oui oui
deletion_requested Le sous-traitant a demandé la suppression ; l'émetteur doit répondre. oui oui
deleted Supprimé avec un motif. Conservé aux archives ; son QR affiche « document supprimé ». oui —
superseded Remplacé par un autre document (superseded_by_control_document_id). oui oui
cancelled Annulé par Fincargo, unité remboursée. non —

Créer ne coûte rien. C'est l'assignation (à votre chauffeur), l'envoi au sous-traitant ou la génération du lien d'accès qui facture. Un DeCa confié à un sous-traitant est facturé à ce moment-là, même incomplet : il reste awaiting_vehicle jusqu'à ce que le camion soit déclaré, et c'est alors que son PDF naît.

Ce qui n'est pas une étape reste dans des champs à part : archived_at (un rangement), public_link_status, les corrections, et return_of_control_document_id (ce document est un retour).

Ce que vous pouvez faire maintenant : available_actions

GET /v1/controldocuments/{id}, ainsi que la réponse de création, renvoient la liste des gestes que votre compte peut faire sur ce document, dans son état actuel :

{
  "id": "…",
  "status": "issued",
  "available_actions": ["correct", "supersede", "finish"]
}
Action Route
assign PATCH /v1/controldocuments/{id}/roles/{role_id}/assign-subaccount
send POST /v1/controldocuments/{id}/roles/{role_id}/send
create_access_link POST /v1/controldocuments/{id}/roles/{role_id}/external-access
declare_vehicle POST /v1/controldocuments/{id}/vehicle
correct POST /v1/controldocuments/{id}/corrections
supersede POST /v1/controldocuments/{id}/supersede
replace POST /v1/controldocuments/{id}/replace (sous-traitant)
delete DELETE /v1/controldocuments/{id} (jamais émis : rien n'est facturé)
delete_with_reason POST /v1/controldocuments/{id}/deletion (émetteur)
request_deletion POST /v1/controldocuments/{id}/deletion (sous-traitant)
approve_deletion, decline_deletion POST /v1/controldocuments/{id}/deletion/approve, /decline
finish POST /v1/controldocuments/{id}/finish

Une action listée est acceptée. Une action qui n'a pas de sens dans cet état n'est pas proposée. Dans la liste (GET /v1/controldocuments), le champ vaut null : relisez le document avant d'agir.

Rattraper ce qui a changé : updated_since

Sans webhook, votre TMS interroge la liste. Pour ne relire que ce qui a bougé :

GET /v1/controldocuments?updated_since=2026-10-20T08:00:00Z
  • Un document est rendu dès que lui ou l'un de ses éléments a changé depuis cet instant (inclus) : rôles (plaque déclarée, chauffeur désigné ou changé), corrections, lignes de marchandise, commentaires, pièces jointes.
  • La page est triée par updated_at, du plus ancien au plus récent : une pagination ne saute aucun changement. Gardez le plus grand updated_at reçu, et repassez-le à l'appel suivant.
  • Les documents archivés, supprimés ou remplacés sont inclus : un rattrapage doit tout voir.

Filtrer par statut

GET /v1/controldocuments?status=awaiting_vehicle&status=deletion_requested

status est répétable. Comme updated_since et external_identifier, il cherche des deux côtés de la ligne d'archivage, sauf si vous passez archived explicitement. external_identifier cherche votre propre référence ; combiné à status, il donne le document en vigueur quand un remplacement partage la référence de l'original.