2 - Lettres en nombre

Soumettre un publipostage

Soumission d'un publipostage, à générer par nos soins (par opposition au publipostage déjà prêt).

Dans votre appel API, outre les options d'envoi, sont attendus :

Votre document principal, qui servira de modèle pour la génération de vos courriers
Vos données, contenant à minima les adresses destinataires (et en option : des champs de fusion, des adresses expéditeur, etc.)
Des annexes éventuelles, à joindre à la fin de chacun des courriers

💡 Dans le cas où vous enverriez un publipostage en LRAR, n'oubliez pas d'ajouter une adresse d'expédition valide sur chacun de vos courriers. Les courriers sans adresse d'expédition seront considérées KO.

💡 Nous vous conseillons de consulter la documentation du endpoint Vérifier vos données pour connaitre les règles qui s'appliquent à votre fichier de données.

post/publipostages/soumettre

Request

Base URL: https://sandbox-api.servicepostal.com
URL: https://sandbox-api.servicepostal.com/publipostages/soumettre
Auth: none declared

Request body

Choix de l'affranchissement pour votre publipostage, qui déterminera les services (suivi du courrier, preuve de distribution) ainsi que la rapidité de distribution. <ul> <li>lrar : lettre recommandée avec accusé de réception (suivi courrier + retour d'un bordereau prouvant la distribution au destinataire, J+3).</li> <li>lr : lettre recommandée simple (suivi courrier mais pas de bordereau de retour, J+3).</li> <li>verte : Lettre verte (J+3)</li> <li>vertesuivi : Lettre verte avec option suivi (J+3)</li> <li>ecopli : Lettre simple ecopli (J+4)</li> <li>performance : Lettre performance (J+2)</li> <li>perfsuivi : Lettre performance avec option suivi (J+2)</li> </ul> Veuillez noter que si certaines adresses sont à l'étranger, les modes d'affranchissements en équivalent international seront utilisés (lettre performance internationale si le type d'envoi que vous avez sollicité ne nécessite pas de suivi, lettre recommandée internationale sinon)

type_enveloppestring

Il n'est plus nécessaire de transmettre ce paramètre. Le format de l'enveloppe est calculé par l'API en fonction du nombre de feuilles des courriers : <ul> <li>Pour une lettre avec moins de 5 feuilles, l'enveloppe est au format C6</li> <li>Pour une lettre avec moins de 9 feuilles, l'enveloppe est au format C5</li> <li>Pour une lettre avec 9 feuilles et plus, l'enveloppe est au format C4</li> </ul> A titre de rappel, le nombre de feuilles est calculé en fonction : <ul> <li>du nombre de pages</li> <li>du mode d'impression (recto ou recto-verso)</li> <li>de la présence ou non d'un porte-adresse</li> </ul>

couleur'nb' | 'couleur'

Couleur d'impression de vos courriers : noir et blanc ou bien couleur. Veuillez noter que ce choix concerne l'ensemble de vos courriers (nous ne pouvons pas imprimer le document principal en couleur et les annexes en noir et blanc)

recto_verso'recto' | 'rectoverso'

Mode d'impression de vots courriers : dans le cas d'une impression recto, le côté verso de chaque feuille sera laissé vierge. Bien sûr, pour des questions écologiques 🌱 (et économiques ! €€), nous vous invitons autant que possible à utiliser l'option recto-verso, qui permettra de réduire le nombre total de feuilles, et donc le poids ainsi que le prix. Veuillez noter que à l'heure actuelle, ce choix concerne l'ensemble des courriers de votre publipostage (nous ne pouvons pas imprimer le document principal en recto et les annexes en recto-verso)

placement_adresse'insertion_page_adresse' | 'premiere_page'

Ce paramètre est facultatif mais il est important de comprendre son usage : le placement adresse va déterminer la façon dont l'adresse du destinataire est intégrée à votre courrier. <ul> <li>insertion_page_adresse : insertion d'un porte-adresse, c'est à dire d'une feuille qui va venir porter l'adresse de votre destinataire. Ainsi, vous avez la garantie qu'une fois mis sous pli, l'adresse ( * ) est mise en page au bon endroit pour apparaître à l'emplacement approprié sous la fenêtre cristal de l'enveloppe, sans qu'elle soit surimprimée sur votre document (puisqu'il s'agit d'une feuille dédiée).</li> <li>premiere_page : l'adresse destinataire ( * ) est placée par nos soins sur la première page de votre document. Cela vous permet d'économiser l'ajout d'un porte adresse (1 feuille en moins) mais vous oblige à vérifier dans quelle mesure cette adresse ne vient pas se superposer par-dessus une partie renseignée de votre document. Pour se faire vous pouvez utiliser notre endpoint de pré-visualisation pour être certains que cette adresse s'intègre proprement. </li> </ul> La valeur par défaut retenue par nos services si vous ne nous précisez pas votre choix est l'insertion d'une page adresse, ce qui permet aux nouveaux clients d'avoir la garantie de ne pas voir leur document altéré. Cependant, si l'emplacement de l'adresse correspond à un espace vierge sur votre document, nous vous invitons à l'exploiter pour diminuer le poids du courrier et donc les coûts. ( * ) voire les adresses (destinataire + expéditeur) dans le cas où vous auriez activé l'affichage de l'adresse expéditeur (voir l'option impression_expediteur juste en-dessous)

impression_expediteurtrue | false

L'impression de l'adresse destinataire est obligatoire bien sûr pour que le courrier puisse être distribué; cette option permet d'indiquer si vous souhaitez également faire apparaître l'adresse expéditeur. Ces adresses seront soit imprimées sur le porte-adresse si vous avez choisi l'option insertion_page_adresse pour le paramètre placement_adresse (voir juste au-dessus), soit au-dessus de la première page de votre document si vous avez choisi l'option premiere_page.

validation_autotrue | false

Si vous êtes confiant sur l'usage du endpoint de soumission et que vous souhaitez nous soumettre un publipostage directement, sans avoir besoin de le valider, vous pouvez forcer la validation automatique en passant le paramètre validation_auto à true. Veuillez noter toutefois que nous conseillons à tous nos clients de passer systématiquement par une phase de validation pour être certains de la forme finale de vos plis, cette option n'est qu'à votre disposition pour une facilité d'usage mais peut représenter un risque si vous n'êtes pas sûrs de ce que vous faites.

ar_scantrue | false

<table style='margin:0px;'><tr style='border-top:none'> <td style='border:none;padding-left:0px;'>Option correspondant à l'accusé de réception dématérialisé:</td> <td style='border:none;'><img src='../images/ARScanSmall.jpg' /></td> </tr></table> Cette option est disponible uniquement avec l'affranchissement LRAR vers la France ou l'international. Si vous mettez ce paramètre à true, au lieu que l'avis de distribution vous revienne physiquement, il est retourné vers nos services, scanné par nos soins. Dès cet instant, il apparaît dans votre espace client Service Postal sur notre site publipostage (rubrique "Mes Mailings"), mais vous pouvez également le récupérer en utilisant le endpoint <a href='/#tag/Lettres-en-nombre/paths/~1publipostages~1%7Buid%7D~1statut/get'>Statut de distribution</a>. Par défaut, si votre courrier est un LRAR et que vous omettez le paramètre, l'avis de passage vous reviendra physiquement à l'adresse expéditeur indiquée au moment de l'appel. <div class='toptip'> 💡 Un <a href='https://fr.wikipedia.org/wiki/Webhook' target='_blank'>webhook</a> est à votre disposition si vous voulez être tenus au courant en temps réel de la mise à disposition des avis de distribution dématérialisés. Ce webhook vous permet aussi d'être informé à chaque étape de la production et du dépôt en poste (pour tous les types de courriers) ainsi que des différentes étapes de distribution de vos courriers suivis, pour les types de courriers possédant un numéro de suivi (lettre recommandée avec ou sans accusé de réception, lettre verte suivie, lettre performance suivie). </div>

referencestring

Reference client, dossier, etc (à votre convenance). Champ libre que vous retrouverez dans votre espace 'mes mailings'. Pour information, cet élément apparaîtra également sur l'avis de distribution dans le cas d'un envoi LRAR.

date_envoistring

Nos services (et donc, notre API également) permettent de planifier l'envoi de publipostages à l'avance. Grâce à ce paramètre, vous pouvez nous indiquer le jour auquel nous déposerons votre publipostage en Poste. Format de date : AAAA-MM-JJ Example : 2023-06-30 <div class='toptip'> ⏰ Pour que le publipostage parte ASAP, il suffit de ne PAS nous envoyer de paramètre date_envoi, et de pré-visualiser et valider votre publipostage dans la foulée. Autrement dit : par défaut (sans précision de date) tous les publipostages, une fois validés sont pris en compte immédiatement. Chez Service Postal, tous les publipostages validés avant midi partent le jour même. Si vous ne précisez pas la valeur de date_envoi (ce qui est le cas le plus classique), votre publipostage partira le jour où vous l'aurez validé. Pour de très gros publipostages qui doivent partir ASAP (à partir de plusieurs milliers), en fonction des contraintes de production la matérialisation et le dépôt en poste pourra s'étaler sur quelques jours, mais les premières centaines de courriers partiront toujours ASAP, c'est à dire au moment de votre validation. </div>

Example request

{
  "type_affranchissement": "lrar",
  "reference": "Référence client VWXYZ-12345",
  "fichier_modele": {
    "nom": "MyBeautifulName.docx",
    "contenu_base64": "<Base64 doc. principal>"
  },
  "fichier_donnees": {
    "nom": "MyAmazingData.csv",
    "contenu_base64": "<Base64 des données CSV>"
  },
  "fichier_annexes": [
    {
      "contenu_base64": "<Base64 d'annexe>"
    }
  ]
}

Response

Opération réussie

codeinteger

Report du code correspondant à la réponse HTTP

messagestring

Détail de la réponse, correspondant au code de succès ou d'erreur

uidstring

Identifiant unique permettant d'accéder à des opérations ultérieures sur ce publipostage (suivi, etc.)

nb_adresses_okinteger

Nombre d'adresses provenant de votre fichier de données, que nous avons détectées comme valides pour constituer un pavé adresse destinataire

nb_adresses_kointeger

Nombre d'adresses provenant de votre fichier de données, que nous avons détectées comme invalides pour constituer un pavé adresse destinataire. Pour vous aider dans la constitution de votre fichier de données, nous avons mis à disposition un endpoint de validation de fichier de données, qui vous permet de pointer les adresses problématiques pour vous permettre de les corriger. Grâce à lui, vous pourrez soumettre un publipostage tout en ayant l'assurance que toutes vos adresses sont valides. Pour soumettre un publipostage, rien n'empêche qu'une partie des adresses soit en erreur, mais nous vous invitons à être particulièrement vigilants sur cette valeur nb_adresses_ko après votre soumission.

fusion_warningsstring

Détail d'analyse des champs de fusion entre votre document principal et votre fichier de données

serviceunknown

affranchissementunknown

totalunknown

Example response

{
  "code": 201,
  "message": "Votre publipostage a été créé avec succès",
  "uid": "p-a54bd707d6e3fb03a9b5333f582e9a57",
  "fusion_warnings": "Aucun champ de fusion n'a été détecté; Champs du CSV non détectés comme champs de fusion dans le document principal : COL1, COL2, COL3;",
  "service": 39,
  "affranchissement": 95,
  "total": 134
}

Changes

No recorded changes to this operation across all 1 revision of this API.