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