Règles automatiques
Configurer la politique de retour de votre organisation — tentatives, retry et retour automatique.
Règles automatiques
Chaque organisation de Swaloo dispose d'une politique de retour (ReturnPolicy) qui décrit comment réagir automatiquement à un échec de livraison : faut-il réessayer, combien de fois, et quand renvoyer le colis à l'expéditeur ?
La politique de retour se consulte et se modifie via l'endpoint /return-policy. Sa configuration est réservée aux administrateurs d'organisation (ROLE_ORG_ADMIN).
Les paramètres de la politique
| Paramètre | Champ | Valeur par défaut | Rôle |
|---|---|---|---|
| Tentatives max | maxDeliveryAttempts | 3 | Nombre de tentatives de livraison avant retour automatique. 0 = pas de retour auto. |
| Délai entre tentatives | retryDelayHours | 24 | Heures d'attente entre deux tentatives automatiques. |
| Retry automatique | autoRetryEnabled | false | Active le réessai automatique pour les raisons éligibles. |
| Retour automatique | autoReturnEnabled | false | Active le retour automatique quand le nombre max de tentatives est atteint. |
| Retour immédiat sur refus | immediateReturnOnRefusal | true | Renvoie immédiatement le colis pour les raisons qui le recommandent (refus, annulation…). |
| Raisons non-réessayables | noRetryReasons | — | Liste de raisons d'échec qui ne déclenchent jamais de retry automatique. |
| Point de retour par défaut | defaultReturnPoint | — | Adresse de retour ; si absente, on utilise le point de collecte d'origine de l'expédition. |
| Notifier à l'échec | notifyOnFailure | true | Prévient l'expéditeur à chaque échec de livraison. |
| Notifier au retour | notifyOnReturn | true | Prévient l'expéditeur quand un retour est initié. |
Que se passe-t-il à un échec de livraison ?
Lorsqu'une tâche de livraison échoue, Swaloo applique automatiquement la politique de retour. Le déroulé est le suivant :
- Le compteur de tentatives de l'expédition est incrémenté et la dernière raison d'échec est enregistrée.
- Si aucune politique n'est configurée, l'événement est journalisé et une action manuelle est requise.
- Si
notifyOnFailureest actif, l'expéditeur est notifié de l'échec. - Swaloo choisit alors l'une des actions suivantes :
| Décision | Condition | Résultat |
|---|---|---|
| Retour immédiat | La raison recommande le retour et immediateReturnOnRefusal est actif | Crée une tâche RETURN de type Refus (refused) |
| Réessai (retry) | La raison est réessayable, autoRetryEnabled actif, raison absente de noRetryReasons, et le nombre de tentatives reste sous la limite | Programme une nouvelle tâche de livraison après le délai configuré |
| Retour (max atteint) | autoReturnEnabled actif et nombre de tentatives ≥ maxDeliveryAttempts | Crée une tâche RETURN de type Échec de livraison (failed_delivery) |
| Action manuelle | Aucun des cas ci-dessus | Aucune tâche créée ; l'événement signale qu'une intervention humaine est nécessaire |
Lorsqu'un retry est programmé, le destinataire est prévenu (SMS / email) avec un lien vers la page publique de suivi et la date de la prochaine tentative, afin qu'il puisse s'organiser. Le livreur dont la livraison a échoué est également notifié.
Raisons non-réessayables
Certaines raisons d'échec ne doivent jamais déclencher un nouvel essai (par exemple un colis endommagé ou perdu). Ces raisons sont listées dans noRetryReasons. Si la raison d'un échec figure dans cette liste, aucun retry automatique n'est tenté : le retour devra être traité manuellement.
Adresse de retour
Pour déterminer où ramener le colis, Swaloo utilise, dans l'ordre :
- un point de retour fourni explicitement lors de l'initiation manuelle ;
- le point de retour par défaut de la politique (
defaultReturnPoint) ; - à défaut, le point de collecte d'origine de l'expédition.
La tâche de retour est programmée pour une livraison dans les 24 heures.
Initier un retour manuellement
Un dispatcher (ROLE_DISPATCHER) peut créer un retour à la main, sans attendre un échec automatique. Il choisit alors le type de retour souhaité. Swaloo crée la tâche RETURN correspondante, enregistre l'événement « Retour initié manuellement » et applique les règles de notification de la politique.
Si aucune politique n'est configurée, ou si la décision automatique aboutit à « action manuelle », c'est au dispatcher d'initier le retour depuis l'expédition concernée.
Voir aussi : Types de retour | Échanges