mf-preuves-courrier

Récupérer les preuves d'un courrier envoyé via l'API Merci Facteur avec getProof — preuve de dépôt, avis de réception signé, preuve de téléchargement d'un recommandé électronique. Utiliser quand il s'

SKILL.md

GitHub

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