Annuler un envoi — API Merci Facteur
deleteEnvoi annule un envoi et les courriers qu'il contient. L'opération est irrémédiable : un envoi annulé ne se restaure pas, et l'issue dépend de l'avancement du courrier dans la chaîne d'impression et de dépôt.
Base URL : https://www.merci-facteur.com/api/1.2/prod/service
Authentification : voir mf-api-authentification.
1. L'appel
DELETE /deleteEnvoi?idEnvoi=<entier>
| Paramètre | Emplacement | Type | Requis | Contenu |
|---|
ww-service-id | en-tête | string | oui | le service ID |
ww-access-token | en-tête | string | oui | un access token valide |
idEnvoi | query | integer | oui | l'envoi_id retourné par sendCourrier |
Réponse en succès : {"success": true}
Réponse en échec (400 / 401) : {"success": false, "error": {"code": "...", "text": "..."}}
const r = await fetch(
`https://www.merci-facteur.com/api/1.2/prod/service/deleteEnvoi?idEnvoi=${idEnvoi}`,
{
method: "DELETE",
headers: {
"ww-service-id": SERVICE_ID,
"ww-access-token": token,
},
}
);
const d = await r.json();
idEnvoi est l'envoi_id rendu par sendCourrier. Une intégration qui ne l'a pas stocké ne peut rien annuler : c'est la raison pratique de le persister systématiquement.
2. Les quatre issues
Un envoi n'est pas un objet figé : il est composé, imprimé, mis sous pli, puis déposé. deleteEnvoi intervient quelque part dans cette chaîne, et son effet réel dépend de l'endroit :
| Issue | Ce qui se passe |
|---|
| Rejet immédiat | L'envoi est trop avancé, rien n'est annulé. |
| Rejet différé | L'annulation est enregistrée mais ne prend pas effet tout de suite. |
| Annulation partielle | Une partie seulement des courriers est annulée ; la facturation est partiellement remboursée. |
| Acceptation intégrale | L'envoi entier est annulé. |
Trois conséquences pour l'intégration :
Ne considère jamais success: true comme « le courrier ne partira pas ». Un succès peut recouvrir une annulation partielle. Sur un envoi multi-destinataires en particulier, une partie des plis peut déjà être partie.
N'affiche pas de montant remboursé calculé côté application. Le remboursement est décidé par Merci Facteur selon l'avancement réel. Toute somme affichée à l'utilisateur avant confirmation est une promesse que l'API n'a pas faite.
Vérifie l'état après coup plutôt que de le déduire. Les webhooks et le suivi (mf-preuves-courrier) disent ce qui est réellement arrivé à chaque courrier. L'appel deleteEnvoi dit seulement que la demande a été prise en compte.
3. Le délai réel
Les courriers validés avant 17 h, du lundi au vendredi, sont imprimés et postés le jour même. Une annulation demandée après ce point de bascule a peu de chances d'aboutir intégralement.
Si l'application doit offrir une fenêtre d'annulation à ses utilisateurs, la façon fiable de la garantir n'est pas deleteEnvoi : c'est de retarder l'appel à sendCourrier. Mets l'envoi en file d'attente côté application, laisse la fenêtre d'annulation s'écouler, puis appelle sendCourrier. Tant que l'appel n'a pas eu lieu, l'annulation est certaine, gratuite et instantanée.
deleteEnvoi est un filet de sécurité pour l'erreur constatée après coup, pas un mécanisme d'annulation garanti.
4. Ce qu'il faut demander avant d'appeler
deleteEnvoi détruit sans retour. Dans un agent, un script ou une automatisation, l'appel ne se déclenche jamais implicitement :
- Confirme l'
idEnvoi avec l'utilisateur avant d'appeler, en rappelant ce que contient cet envoi (destinataires, nombre de courriers) si l'information est disponible.
- N'annule jamais en boucle sur une liste d'envois sans validation explicite de chaque élément, ou du lot en toute connaissance de cause.
- N'appelle pas
deleteEnvoi en réaction à un timeout de sendCourrier. Un timeout laisse l'issue indéterminée : annuler un envoi dont on ignore s'il existe produit soit un échec, soit l'annulation d'un envoi qu'on voulait garder. Le traitement correct du timeout est dans mf-envoi-courrier, section 5.
5. Diagnostic
| Symptôme | Cause à vérifier |
|---|
401 | token expiré, ou ww-service-id absent à côté de ww-access-token |
400 | idEnvoi absent, non entier, ou n'appartenant pas à ce compte |
success: true mais le courrier arrive quand même | annulation partielle, ou rejet différé — voir section 2 |
| Annulation systématiquement refusée | demande postérieure au dépôt La Poste — voir section 3 |