Skip to content

Vos chauffeurs

Un DeCa est attribué à un chauffeur : c'est lui qui le reçoit dans l'application et le présente au contrôle. Votre TMS a ses propres chauffeurs, avec ses propres identifiants. Cette page explique comment les relier aux nôtres une fois, puis désigner un chauffeur par votre référence.

Droits nécessaires : directory:read pour lire, directory:write pour poser une référence (voir Authentification).

1. Lister vos chauffeurs

GET /v1/fleet/drivers

{
  "drivers": [
    {
      "id": "6f1c…",
      "external_identifier": null,
      "display_name": "Juan Pérez",
      "email": "juan@transportes.example",
      "phone_number": "+34600000000",
      "status": "active",
      "created_at": "2026-10-01T08:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1
}
  • status : active (peut se connecter et recevoir des documents), invited (invitation envoyée, pas encore acceptée : un document attribué l'attendra dans l'application), blocked (accès coupé, ne peut pas être attribué).
  • Filtres : external_identifier (exact), status, et la pagination limit / offset.
  • Seuls les chauffeurs de votre compte apparaissent.

La création et l'invitation des chauffeurs se font dans la console (Hub (la grille de l'en-tête) → Référentiel → Chauffeurs).

2. Poser votre référence sur chaque chauffeur

Rapprochez vos chauffeurs des nôtres (par téléphone ou par e-mail), puis posez votre identifiant :

PATCH /v1/fleet/drivers/{id}
{ "external_identifier": "DRV-0042" }

La référence est unique dans votre compte. Une valeur déjà portée par un autre de vos chauffeurs est refusée (409, fleet.driver_reference_already_exists), et le refus donne l'identifiant de ce chauffeur dans existing_id. null retire la référence.

3. Désigner le chauffeur par votre référence

Partout où un DeCa attend un chauffeur, driver_ref remplace assigned_subaccount_id ou subaccount_id :

Geste Où
Créer un DeCa déjà attribué (il est émis et facturé aussitôt) POST /v1/controldocuments, dans le rôle CARRIER : "driver_ref": "DRV-0042"
Attribuer un DeCa créé sans chauffeur PATCH /v1/controldocuments/{id}/roles/{role_id}/assign-subaccount : {"driver_ref": "DRV-0042"}
Changer de chauffeur (correction tracée sur le PDF) POST /v1/controldocuments/{id}/corrections : {"field": "DRIVER", "new_value": "…", "driver_ref": "DRV-0042"}
Attribuer une tournée entière POST /v1/tours/{id}/assignment : {"driver_ref": "DRV-0042"}

Donnez l'un ou l'autre, jamais les deux. Une référence inconnue, ou qui appartient à un autre compte, est refusée comme un identifiant qui n'est pas à vous (400, freight_document.subaccount_not_eligible).