Signature électronique

Cette page décrit, du point de vue d'un TMS intégrateur, comment déclencher une demande de signature électronique sur un Freight Document, comment suivre son avancement, et comment interpréter les signatures déjà apposées. Elle reste au niveau fonctionnel — les paramètres cryptographiques précis ne sont pas nécessaires pour intégrer ce mécanisme et ne sont pas couverts ici.

Ce qui déclenche une signature

Cinq types de transfert peuvent être signés sur un document :

`transfer_type`	Qui signe	Effet sur le statut du document
`COLLECTION`	Le rôle `PLACEOFTAKINGOVER` (prise en charge initiale)	`ISSUED` → `TRANSIT`
`COLLECTION_ACCEPTANCE`	Le rôle `CARRIER` (le chauffeur/transporteur, au moment même de la collecte)	Aucun — voir ci-dessous, cette signature conditionne `DELIVERY`
`DELIVERY`	Le rôle `PLACEOFDELIVERY` (livraison finale)	`TRANSIT` → `DELIVERED`
`HANDOVER`	Le rôle `CARRIER` (remise de garde à un relais)	Aucun — voir Carrier-to-carrier
`ACCEPTANCE`	Le rôle `SUBSEQUENTCARRIER` (prise en charge du relais)	Aucun

COLLECTION et DELIVERY font avancer la machine à états du document dès que la signature est validée — c'est la signature elle-même qui déclenche la transition, pas un appel séparé. COLLECTION_ACCEPTANCE, HANDOVER et ACCEPTANCE n'ont aucun effet sur le statut global : seule la trace de la signature (visible via GET .../signatures et l'historique d'audit) les enregistre.

COLLECTION_ACCEPTANCE correspond à la case 23 du formulaire CMR papier (le transporteur) — distincte de la case 22 (expéditeur, COLLECTION) et de la case 24 (destinataire, DELIVERY), voir Pièces jointes & PDF. Elle est également distincte du relais HANDOVER/ACCEPTANCE : c'est le même transporteur qui vient d'effectuer la collecte qui atteste ici avoir reçu la marchandise, pas un changement de garde entre deux sociétés.

DELIVERY est bloquée tant que COLLECTION_ACCEPTANCE n'a pas eu lieu sur le document. Ce contrôle s'applique aussi bien à la création de la demande de signature (POST .../signature-challenges) qu'à sa complétion — une tentative avant que COLLECTION_ACCEPTANCE existe échoue dans les deux cas avec le même code signature.collection_acceptance_required (409, voir Codes d'erreur). Dans le scénario nominal mono-transporteur, l'application chauffeur enchaîne automatiquement COLLECTION puis COLLECTION_ACCEPTANCE sur le même appareil, sans action supplémentaire de votre part — voir Mono-transporteur.

Déclencher une demande de signature

POST /v1/freightdocuments/{id}/signature-challenges
{ "transfer_type": "COLLECTION" }

Nécessite le rôle habilité pour au moins un type de transfert sur ce document (voir le tableau ci-dessus) — un SUBMITTER seul, par exemple, ne peut pas déclencher de demande de signature.

La réponse contient un nonce : c'est le jeton qui porte toute la suite du parcours de signature. Dans le scénario physique nominal, l'appareil qui a déclenché la demande (typiquement celui du chauffeur, pour une collecte ou une livraison) affiche ce nonce sous forme de QR code ; c'est le signataire (l'expéditeur, le destinataire, ou son magasinier) qui scanne ce QR avec son propre appareil, ouvrant ainsi le parcours de signature dans son propre contexte — jamais sur l'appareil de quelqu'un d'autre, sauf dans le cas de repli décrit plus bas.

Le nonce a une durée de validité courte (moins de deux minutes) tant que le signataire n'a pas encore engagé le parcours, et ne peut être utilisé qu'une seule fois. Dès que le signataire soumet son numéro de téléphone, cette fenêtre est automatiquement prolongée à plusieurs minutes pour couvrir le reste du parcours (SMS, vérification, éventuelles photos/documents) — vous n'avez rien à faire pour cela, et il n'est pas nécessaire de réémettre une demande simplement parce qu'un signataire prend son temps une fois engagé. Une demande expirée ou déjà utilisée doit être réémise — voir Codes d'erreur.

Ce qui se passe côté signataire (pour votre information — pas d'appel direct de votre part)

Une fois le QR scanné, l'application du signataire (PWA e-CMR) prend le relais pour le reste du parcours :

Première signature d'une personne : son numéro de téléphone est vérifié par SMS, puis une clé de signature propre à son appareil est créée — sans jamais que cette clé transite par vos serveurs.
Signatures suivantes : la personne est reconnue automatiquement par son numéro de téléphone ; aucune nouvelle vérification SMS n'est nécessaire tant que sa clé reste active.
La signature elle-même est produite sur l'appareil du signataire et vérifiée côté plateforme.

Votre intégration n'a rien à orchestrer pendant cette étape — vous recevez le résultat final (voir ci-dessous), que ce soit via un webhook de changement de statut (pour COLLECTION/DELIVERY) ou en interrogeant GET .../signatures.

Commentaire, photos et documents optionnels capturés au moment de la signature — l'écran de signature peut soumettre un texte libre (comment_text) dans la même requête qui complète la signature. Si fourni (un texte vide ou uniquement composé d'espaces est traité comme absent), un Comment de type INFO est créé dans la même transaction, lié à cette signature précise via un champ signature_id — voir Événements & Commentaires. Une ou plusieurs photos/documents pris sur le même écran suivent un circuit différent (chacun doit d'abord être uploadé et confirmé — via les endpoints attachments habituels si l'appelant a un compte, ou via l'équivalent public POST /v1/signatures/attachments scopé au nonce de signature pour un signataire sans compte — avant même que la signature existe) mais aboutissent au même lien : la requête de complétion de signature accepte une liste attachment_ids optionnelle désignant ces pièces jointes déjà confirmées, et la signature une fois créée y est reliée via attachments.signature_id sur chacune — voir Pièces jointes & PDF. Fournir un id dans attachment_ids qui n'existe pas ou n'appartient pas à ce document rejette toute la requête avec attachment.not_found.

Interpréter `signature_level`

Chaque signature enregistrée porte un signature_level :

ADES — signature produite avec la clé propre au signataire, sur son propre appareil. C'est le niveau nominal, attendu dans l'écrasante majorité des cas.
SIGN_ON_GLASS — repli explicite utilisé quand le signataire n'a pas d'appareil personnel disponible : il trace sa signature manuscrite directement sur l'appareil du chauffeur, après identification par nom et téléphone (sans vérification SMS, faute d'appareil pour la recevoir).

Ne traitez jamais ces deux niveaux comme équivalents dans votre propre logique métier. SIGN_ON_GLASS reste une signature valide et enregistrée, mais avec un niveau de preuve délibérément inférieur — si votre TMS a besoin de distinguer ou signaler ce cas (par exemple à un client final), signature_level est le champ à afficher.

Consulter les signatures d'un document

GET /v1/freightdocuments/{id}/signatures

Retourne, dans l'ordre chronologique, chaque signature déjà apposée sur le document : type de transfert, qui a signé (signer_subaccount_id), niveau de preuve, et un lien de vérification.

Vérification publique d'une signature

Chaque signature expose un verify_url — un endpoint public, sans authentification, qui retourne un résumé vérifiable indépendamment (rôle du signataire, niveau de preuve, horodatage). Cet endpoint ne retourne jamais l'identité personnelle du signataire (téléphone, nom) — seulement son rôle contractuel sur le document (CARRIER, PLACEOFDELIVERY, ...).

Révocation d'une clé de signature

Si l'appareil d'un signataire est perdu ou volé, sa clé de signature peut être révoquée — par la personne elle-même ou par le compte organisation dont elle dépend. Une révocation ne remet jamais en cause les signatures déjà produites avec cette clé ; elle empêche seulement toute nouvelle signature tant qu'un nouvel enrôlement (identique au premier) n'a pas eu lieu.