Preuves et suivi d'un courrier — API Merci Facteur

Un recommandé sans sa preuve ne vaut rien juridiquement. Ce document couvre la récupération des preuves et du suivi. L'envoi est dans mf-envoi-courrier, l'authentification dans mf-api-authentification.

Base URL : https://www.merci-facteur.com/api/1.2/prod/service En-têtes sur tous les appels : ww-service-id, ww-access-token.

1. Quels envois produisent des preuves

Les preuves n'existent que pour les modes d'envoi qui en génèrent :

modeEnvoi	Preuves récupérables par API
normal	aucune — la lettre verte n'a ni suivi ni preuve
suivi	preuve de dépôt
lrar	preuve de dépôt — l'AR signé revient en papier à l'expéditeur, pas par l'API
lrare	preuve de dépôt + AR numérisé, poussé par l'API
ere_otp_mail, ere_otp_sms	preuve de dépôt + preuve de téléchargement

Si l'utilisateur veut archiver une preuve, ce choix se fait au moment de l'envoi, pas après. Un courrier parti en normal ne produira jamais de preuve, quelle que soit la suite.

Le piège, c'est lrar. C'est le recommandé que tout le monde nomme par réflexe, et son avis de réception arrive dans une boîte aux lettres physique. Une application qui doit archiver l'AR ou en déclencher quelque chose a besoin de lrare : même valeur juridique, AR numérisé et poussé par webhook. Si le code d'envoi utilise lrar et que le code de récupération attend un AR numérique, l'intégration ne marchera jamais — et ça se découvre des semaines plus tard.

2. Une preuve n'existe pas avant son événement

Une preuve apparaît quand l'événement qu'elle atteste a eu lieu :

• la preuve de dépôt après le dépôt effectif chez La Poste, donc au plus tôt le soir de l'impression ;
• l'avis de réception quand le destinataire signe, ce qui peut prendre des jours, ou ne jamais arriver ;
• la preuve de téléchargement d'un recommandé électronique quand le destinataire s'identifie et ouvre le document, ou jamais s'il ne le fait pas.

Deux conséquences :

Ne récupère pas une preuve juste après sendCourrier. Elle n'existe pas. Un appel immédiat échoue, et un code qui traite cet échec comme une erreur définitive est faux.

Ne fais pas de polling. Merci Facteur pousse chaque étape par webhook, sur l'URL déclarée dans l'onglet « API » de l'interface Merci Facteur Pro — y compris les événements pdd et are qui signalent qu'une preuve est prête, et la transportent (section 3). Tout se déclenche en réaction à ces événements, jamais dans une boucle. Le contrat complet des webhooks est dans mf-envoi-courrier, section 6.

3. Les preuves arrivent souvent toutes seules

Avant d'écrire un appel à getProof, regarde les webhooks : deux d'entre eux transportent déjà le document.

Événement	statut_courrier	Champ	Contenu
pdd	scan_pdd	detail[].pdd_base64_pdf	le PDF de la preuve de dépôt, en base64 — courriers suivis et recommandés
are	retour_are	detail[].are_base64_jpeg	le JPEG de l'AR signé, en base64 — lrare uniquement

Sur ces deux cas, l'intégration correcte est : recevoir le webhook, décoder le base64, stocker le fichier. Aucun appel API. Un agent qui écrit un getProof pour récupérer une preuve de dépôt réinvente un aller-retour dont il a déjà le résultat dans la requête qu'il vient de recevoir.

getProof sert dans trois cas seulement : la preuve de téléchargement d'un recommandé électronique (document=telechargement), la récupération d'une preuve perdue parce que le webhook a échoué ou n'était pas encore branché, et un rattrapage historique sur des envois antérieurs.

3 bis. Où trouver le numéro de suivi

sendCourrier retourne un envoi_id. Un envoi peut contenir plusieurs courriers — un par destinataire — et chaque courrier a son propre numéro de suivi. C'est ce numéro, pas l'envoi_id, que getProof attend.

Ne confonds pas les deux références que porte chaque courrier dans les webhooks :

Champ	Exemple	Ce que c'est
ref_courrier	123456-789123456	la référence interne Merci Facteur du courrier
tracking_number	2C123456789	le numéro de suivi La Poste — c'est lui que getProof attend
ref_interne	client_123	ta propre référence, celle que tu as passée à l'envoi

Passer ref_courrier à getProof échoue. C'est tracking_number.

Le tracking_number apparaît à l'événement printed, quand le courrier papier est imprimé. Il n'existe pas avant : l'événement new ne le porte pas. Il est également présent sur les événements suivants du cycle de vie (pdd, are, delivered…).

tracking_number vaut null pour un courrier parti en normal : la lettre verte n'a pas de suivi, donc pas de numéro, donc pas de preuve. Teste ce null avant d'écrire quoi que ce soit en base, plutôt que de découvrir des chaînes "null" six mois plus tard.

Stocke tracking_number à la réception de printed, associé à l'objet métier concerné. Un courrier dont le tracking_number n'a pas été conservé est un courrier dont on ne pourra plus récupérer la preuve par API.

N'implémente pas de boucle de polling pour découvrir les numéros de suivi. Les webhooks sont la voie prévue. Si l'application ne peut vraiment pas exposer d'URL — et c'est une contrainte à remettre en cause avant de la contourner — demande au support technique de Merci Facteur plutôt que d'interroger l'API en boucle.

4. Récupérer une preuve

GET /getProof?trackingNumber=<string>&document=<string>

Paramètre	Emplacement	Requis	Contenu
ww-service-id	en-tête	oui	le service ID
ww-access-token	en-tête	oui	un access token valide
trackingNumber	query	oui	le tracking_number du courrier (section 3 bis)
document	query	oui	depot, reception ou telechargement

Les trois valeurs de document :

Valeur	Document obtenu	Disponible pour
depot	preuve de dépôt	suivi, lrar, lrare, ere_otp_mail, ere_otp_sms
reception	avis de réception	lrar, lrare
telechargement	preuve de téléchargement	ere_otp_mail, ere_otp_sms

N'essaie aucun autre libellé : il n'y en a pas trois autres à deviner.

La réponse est en base64

Le document revient encodé en base64, accompagné d'un champ format_return qui indique son format réel (PDF ou JPEG). C'est ce format_return qui détermine l'en-tête à associer pour écrire le fichier sur disque ou l'afficher — ne présume pas le PDF.

const r = await fetch(
  `https://www.merci-facteur.com/api/1.2/prod/service/getProof` +
    `?trackingNumber=${encodeURIComponent(ref)}&document=reception`,
  { headers: { "ww-service-id": SERVICE_ID, "ww-access-token": token } }
);
const d = await r.json();

const mime = {
  pdf: "application/pdf",
  jpeg: "image/jpeg",
  jpg: "image/jpeg",
}[String(d.format_return).toLowerCase()];

if (!mime) throw new Error("format_return inattendu : " + d.format_return);

// Écriture sur disque
await fs.writeFile(`preuve-${ref}.${d.format_return}`, Buffer.from(d.document, "base64"));

// Ou affichage / téléchargement côté client
// `data:${mime};base64,${d.document}`

Trois erreurs à éviter :

• Coder en dur application/pdf. Un avis de réception numérisé peut revenir en JPEG. Lis format_return.
• Réencoder le base64. Le champ est déjà encodé : il se décode, il ne se traite pas comme du texte.
• Servir la preuve au navigateur en la re-téléchargeant à chaque affichage. Décode une fois, stocke le fichier (section 5), sers-le depuis ton stockage.

5. Archiver, pas seulement afficher

Une preuve a une valeur juridique : elle sert à démontrer, plus tard et devant un tiers, qu'un courrier a été déposé ou reçu. Deux règles pratiques :

Stocke le fichier, pas un lien. Une URL de preuve peut expirer ou changer. L'intégration qui a besoin de la preuve dans deux ans doit détenir le fichier, dans son propre stockage, associé à l'objet métier concerné (contrat, litige, résiliation, relance).

Enregistre la date de récupération et le numéro de suivi à côté du fichier. Un PDF de preuve isolé, sans le contexte de l'envoi auquel il se rattache, n'est pas exploitable.

5 bis. Lire un statut

Chaque entrée de webhook porte statut_courrier (le code) et statut_description (le texte lisible). Les codes qui décident d'une bifurcation métier :

Courriers papier

Code	Événement	Ce que ça veut dire
wait	new	en attente d'impression — annulation encore possible
imprime	printed	imprimé, posté sous peu — porte le tracking_number
pris_en_charge	new-state	pris en charge par La Poste
attente_presentation	new-state	en attente de distribution
distribution_en_cours	new-state	en cours de distribution
attente_au_guichet	new-state	avis de passage déposé, à retirer au bureau de poste
probleme_en_cours	error	La Poste rencontre un problème
non_distribuable	error	courrier non distribuable
retour_expediteur	error	retourné à l'expéditeur
distribue	delivered	distribué au destinataire — fin d'acheminement
distribue_expediteur	pnd	revenu à l'expéditeur — fin d'acheminement, c'est le NPAI
archivage_pnd	pnd	NPAI d'un lrare archivé chez Merci Facteur pour 3 ans
retour_are	are	AR numérisé disponible
scan_pdd	pdd	preuve de dépôt disponible

Les envois internationaux ajoutent des statuts de transit et de douane (entree_douane, sortie_douane, retenu_douane, transit_pays_intermediaire, traitement_pays_destination, prix_en_charge_pays_destinataire). Ils sont informatifs : ne construis pas de logique métier dessus.

Courriers électroniques

Code	Événement	Ce que ça veut dire
wait	new	en attente d'envoi
envoye	sended	envoyé au destinataire
accept_wait	new-state	en attente d'acceptation
accept_lock	error	bloqué 3 h après 6 échecs d'identification OTP
accept_notification_error	error	email erroné ou boîte pleine — fin d'acheminement
accepted	delivered	accepté et AR signé
accepted_downloaded	delivered	accepté, AR signé, et document téléchargé
expired	pnd	non accepté dans le délai imparti
refused	pnd	refusé par le destinataire

Trois règles pour coder contre ces statuts :

• Teste le code, pas la description. statut_description est du texte lisible avec une date dedans, il change ; statut_courrier est stable.
• Identifie les fins d'acheminement. distribue, distribue_expediteur, accept_notification_error, expired, refused : au-delà, plus rien n'arrivera. C'est là qu'un processus en attente doit être débloqué, pas laissé en suspens indéfiniment.
• Un error n'est pas toujours final. probleme_en_cours peut être suivi de probleme_resolu et la distribution reprendre. Ne clôture pas un dossier sur le premier error.

6. Le cas NPAI

Un courrier peut revenir non distribué — NPAI, « n'habite pas à l'adresse indiquée ». C'est un événement poussé par webhook, et c'est le seul moyen de l'apprendre : aucune preuve ne sera produite, et l'absence de preuve n'est pas en soi un signal exploitable.

Une intégration qui envoie du recommandé sans écouter les webhooks ne saura jamais qu'un pli est revenu. Si l'utilisateur construit un flux de relance ou de mise en demeure, le traitement du NPAI n'est pas optionnel : c'est précisément le cas où le processus métier doit bifurquer.

7. Diagnostic

Symptôme	Cause à vérifier
Aucune preuve disponible, envoi pourtant réussi	modeEnvoi à normal — voir section 1
Preuve introuvable juste après l'envoi	l'événement n'a pas encore eu lieu — voir section 2
trackingNumber refusé	envoi_id ou ref_courrier passé à la place de tracking_number — voir section 3 bis
tracking_number vide en base	courrier parti en normal, ou webhook printed non écouté
Appel getProof pour une preuve de dépôt	inutile : le webhook pdd la contient déjà — voir section 3
document=reception refusé	l'envoi n'est pas un lrar/lrare — voir le tableau de la section 4
Fichier écrit illisible	format_return ignoré, ou base64 réencodé au lieu d'être décodé
AR jamais disponible	le destinataire n'a pas signé, ou le pli est revenu en NPAI — voir section 6
401	token expiré, ou ww-service-id absent à côté de ww-access-token