1 - Lettres unitaires

Envoyer une lettre

Envoi immédiat d'une lettre, en un seul appel.

C'est la méthode la plus simple et la plus directe pour nous pousser un courrier. Toutes les options relatives à votre lettre, ainsi que votre document (et ses éventuelles annexes) sont à inclure dans le corps de la demande, et en retour notre API vous confirme la bonne prise en compte en vous renvoyant :

un identifiant unique (UID) pour ce courrier
Example : l-3fe173a7820bbcb1d78f854eb1cc2738
toutes les options d'envoi déduites ou prises par défaut
les urls dans le cloud ☁️ sur lesquelles nous hébergeons vos documents (doc. principal et annexes éventuelles)
le prix de votre courrier, avec le détail de répartition entre l'affranchissement et le service
ou bien un message d'erreur si votre demande est invalide ou mal formée

Lorsque vous passerez en production, si votre appel sur ce endpoint vous renvoie bien votre identifiant de courrier comme prévu, vous avez la garantie que cette demande parvienne à nos équipements de production pour matérialisation immédiate et envoi le soir même. Tant que vous êtes sur l'API de sandbox, bien sûr aucun courrier ne sera produit ni facturé, le but de cet environnement est de vous faire découvrir toutes les fonctionnalités comme si vous étiez en production, mais de manière fictive. Ainsi, vous pouvez prévoir tous vos développements sereinement pour être 100% prêts le jour du passage en production.

🚚 Si vous appelez notre API avant 17h30, nous déposerons votre courrier en plateforme industrielle courrier (PIC de Bois d'Arcy, 78) le soir même; son acheminement peut donc démarrer pendant la nuit, pour un délai de distribution optimal. Cette souplesse offerte jusqu'à la fin de journée et sans frais supplémentaires, fait partie des engagements Service Postal 🚀 et nous différencie de nos concurrents.

Dans la liste ci-dessous des paramètres d'entrée, les champs notés comme required sont obligatoires, ceux pour lesquels cette mention est absente sont facultatifs.

post/lettres

Request

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

Request body

uidstring

Choix de l'affranchissement pour votre courrier, 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>

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 : <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>

enveloppestring

Il n'est plus nécessaire de transmettre ce paramètre. L'enveloppe possède deux fenêtres laissant apparaître l'adresse destinataire (obligatoire pour la bonne distribution de votre pli) et potentiellement l'adresse expéditeur (si vous avez opté pour cette option, voir plus bas le paramètre impression_expediteur)

couleur'nb' | 'couleur' required

Couleur d'impression de votre courrier : noir et blanc ou bien couleur. Veuillez noter que ce choix concerne l'ensemble de votre courrier (nous ne pouvons pas imprimer une partie en couleur et une autre en noir et blanc)

recto_verso'recto' | 'rectoverso'

Mode d'impression de votre courrier : 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.

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)

surimpression_adresses_documenttrue | false

Cette option correpond au cas d'utilisation pour lequel votre document contient déjà le pavé adresse destinataire (voire également expéditeur), et vous souhaitez que ce pavé soit celui qui soit conservé tel quel pour apparaître sous la fenêtre de l'enveloppe. Dans ce cas, si vous mettez ce paramètre à false, votre document sera mis sous pli en l'état. L'usage de cette option n'a de sens que si vous décidez de ne pas utiliser de porte adresse (paramètre "placement_adresse" = "première_page"). Si vous pensez être intéressé par cette option, nous attirons particulièrement votre attention sur les points suivants, qui sont très importants : <ul> <li> Il est de votre responsabilité de vous assurer que l'emplacement de l'adresse destinataire correspond parfaitement au type d'enveloppe que vous avez choisi. En particulier il serait du coup très hasardeux de nous passer comme paramètre auto pour l'enveloppe pour un tel envoi </li> <li> Le strict respect des normes de La Poste doit être respecté, sans quoi la bonne distribution pourrait être compromise (les éléments constitutifs de l'adresse, le nombre de caractères par ligne, la police de caractères, les marges pour la fenêtre de l'enveloppe ...) </li> <li> Si vous retenez cette option, il reste indispensable de nous fournir l'adresse destinataire dans les champs appropriés de adresse_destination pour que nous puissions affranchir correctement le pli en fonction de sa destination (France, étranger, ...) </li> </ul>

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 par-dessus la première page de votre document si vous avez choisi l'option premiere_page.

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 et scanné par nos soins. Dès cet instant, il apparaît dans votre espace client Service Postal (rubrique "Mes Envois"), mais vous pouvez également le récupérer en utilisant le endpoint <a href='/#tag/Lettres-unitaires/paths/~1scannedproof~1letter~1%7Buid%7D/get'>AR scanné</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 tenu 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>

ar_expediteur_champ1string

Dans le cas d'un courrier LRAR et si vous optez pour l'accusé de réception dématérialisé, vous avez la possibilité d'exploiter à votre guise 2 lignes d'adresse qui apparaîtront sur le bordereau de retour. Cela peut être pratique pour garder trace d'un numéro de dossier, d'une référence client, etc. Chaque ligne doit faire au maximum 38 caractères (contrainte imposée par les normes de La Poste) Le paramètre ar_expediteur_champ1 correspond à la première ligne. <img src='../images/ARScanLines.jpg' />

ar_expediteur_champ2string

Deuxième ligne de personalisation dans le cas d'un LRAR avec accusé de réception dématérialisé.

referencestring

Reference dossier ou client (50 caractères maximum). Champ libre qui vous permet de rattacher à un courrier un identifiant provenant de vos services. Cet élément apparaîtra sur l'avis de distribution dans le cas d'un envoi LRAR. <img src='../images/ARScanRef.jpg' />

nom_entitestring

Entité Service postal pour facture analytique (100 caractères maximum, en lettres majuscules uniquement) 💰 Notre API intègre la notion de facture analytique; si vous envoyez des courriers pour le compte de tiers que vous souhaitez refacturer, vous pouvez indiquer au moment de l'envoi l'entité correspondante à cette commande. Ainsi en fin de mois, vous aurez sur votre facture le détail des consommations pour chaque entité, vous permettant de refacturer précisément pour chacun des tiers le montant précis de ce qu'il vous doit. Ce champ est exploité uniquement sur l'environnement de production.

nom_dossierstring

Nom du dossier pour facture analytique (50 caractères maximum) Ce champ est exploité uniquement sur l'environnement de production.

nom_sousdossierstring

Nom du sous-dossier pour facture analytique (100 caractères maximum) Ce champ est exploité uniquement sur l'environnement de production.

date_envoistring

Nos services (et donc, notre API également) permettent de planifier l'envoi de courriers à l'avance. Grâce à ce paramètre, vous pouvez nous indiquer le jour auquel nous déposerons votre courrier en Poste. Format de date : AAAA-MM-JJ Example : 2023-06-30 <div class='toptip'> ⏰ Pour que le courrier parte ASAP, il suffit de ne PAS nous envoyer de paramètre date_envoi. Autrement dit : par défaut (sans précision de date) tous les courriers poussés sont pris en compte immédiatement. Chez Service Postal, tous les courriers soumis avant 17h30 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 courrier part donc : <ul> <li>le jour même de votre appel à /lettre (cas de l'envoi direct)</li> <li>le jour même de votre appel à /valider (cas de l'envoi avec pré-visualisation puis validation)</li> </ul> Si votre courrier est soumis après 17h30, il sera déposé dans le circuit de distribution de La Poste le lendemain à 18h. </div>

Example request

{
  "recto_verso": "rectoverso",
  "ar_expediteur_champ1": "Référence : CL-06310/07",
  "ar_expediteur_champ2": "Facture : FC-06310-2212",
  "adresse_expedition": {
    "civilite": "M.",
    "prenom": "Jacques",
    "nom": "Martin",
    "nom_societe": "JM Productions",
    "adresse_ligne1": "12 rue du Gai Vigneron",
    "adresse_ligne2": "Bâtiment C",
    "code_postal": "33000",
    "ville": "BORDEAUX",
    "pays": "FRANCE"
  },
  "adresse_destination": {
    "civilite": "M.",
    "prenom": "Léon",
    "nom": "Zitrone",
    "nom_societe": "ORTF",
    "adresse_ligne1": "66 avenue des Champs Elysées",
    "adresse_ligne2": "Service secrétariat général",
    "code_postal": "75008",
    "ville": "PARIS",
    "pays": "FRANCE"
  },
  "variables": {
    "reference_client": "CL-06310/07",
    "numero_facture": "FC-06310-2212",
    "civilite": "Monsieur",
    "prenom": "Léon",
    "nom": "Zitrone"
  },
  "fichier": {
    "contenu_base64": "<Base64 doc. principal>"
  },
  "fichier_annexes": [
    {
      "contenu_base64": "<Base64 d'annexe>"
    }
  ]
}

Response

Opération réussie

uidstring

L'identifiant unique ("Unique ID") généré par nos systèmes et associé à votre courrier. Vous pouvez utiliser cet identifiant plus tard, par exemple pour demander son numéro de suivi, ou bien suivre son état de distribution. A transmettre également au endpoint de validation lorsque vous souhaitez confirmer la commande d'un courrier que vous avez préalablement visualisé.

type_enveloppe'c4' | 'c5' | 'c6'

Si vous avez choisi "auto" comme type d'enveloppe dans votre requête, ce paramètre vous permet de savoir quel format d'enveloppe a été retenu par le moteur de l'API. En fonction du nombre de feuilles que contient votre courrier, le choix de certaines enveloppes sera impossible.

enveloppe'fenetre' | 'imprime'

couleur'nb' | 'couleur'

recto_verso'recto' | 'rectoverso'

placement_adresse'premiere_page' | 'insertion_page_adresse'

surimpression_adresses_documentboolean

impression_expediteurboolean

ar_scanboolean

ar_expediteur_champ1string

ar_expediteur_champ2string

nom_entitestring

Entité Service postal pour facture analytique en lettres majuscules UNIQUEMENT

nom_dossierstring

Nom du dossier pour facture analytique (50 caractères maximum)

nom_sousdossierstring

Nom du sous-dossier pour facture analytique (100 caractères maximum)

date_envoistring

referencestring

Reference client (50 caractères maximum)

code_barreboolean

affranchissementstring

Prix de l'affranchissement, hors taxes. Pour information il n'y a pas de TVA sur l'affranchissement donc dans l'absolu, ce montant correspond également au prix TTC.

servicestring

Prix du service (hébergement des données et documents dans le cloud, papiers, encres, enveloppes, dépôt quotidien dans le circuit de distribution de La Poste), hors taxes. Si vous êtes détenteur d'un abonnement chez Service Postal, une réduction s'applique sur le montant du service; ce prix inclut donc une telle réduction le cas échéant. Si vous voulez connaître nos offres d'abonnement, n'hésitez pas à les consulter notre site <a href='https://www.servicepostal.com/lettre-en-ligne/entreprises/#tarifs_offers' target='_blank'>Service Postal</a>. Pour obtenir un montant TTC, la TVA sur le service est de 20 % (à rajouter donc, si vous souhaitez un montant TTC)

totalstring

Coût total de votre courrier HT = prix de l'affranchissement HT + prix du service HT

affranchissement_basestring

Prix public (non abonné) de l'affranchissement, hors taxes.

service_basestring

Prix public (non abonné) du service (hébergement des données et documents dans le cloud, papiers, encres, enveloppes, dépôt quotidien dans le circuit de distribution de La Poste), hors taxes. Pour obtenir un montant TTC, la TVA sur le service est de 20 % (à rajouter donc, si vous souhaitez un montant TTC)

total_basestring

Coût total public (non abonné) de votre courrier HT = prix de l'affranchissement HT + prix du service HT

Example response

{
  "uid": "l-3fe173a7820bbcb1d78f854eb1cc2738",
  "type_enveloppe": "c5",
  "enveloppe": "fenetre",
  "adresse_expedition": {
    "civilite": "M.",
    "prenom": "Jacques",
    "nom": "Martin",
    "nom_societe": "JM Productions",
    "adresse_ligne1": "12 rue du Gai Vigneron",
    "adresse_ligne2": "Bâtiment C",
    "code_postal": "33000",
    "ville": "BORDEAUX",
    "pays": "FRANCE"
  },
  "adresse_destination": {
    "civilite": "M.",
    "prenom": "Léon",
    "nom": "Zitrone",
    "nom_societe": "ORTF",
    "adresse_ligne1": "66 avenue des Champs Elysées",
    "adresse_ligne2": "Service secrétariat général",
    "code_postal": "75008",
    "ville": "PARIS",
    "pays": "FRANCE"
  },
  "fichier": {
    "url": "https://sandbox-example-file.servicepostal.com/c456984a48ed710f6a62dcb78dd65e89_01-01-2666.pdf"
  },
  "variables": {
    "reference_client": "CL-06310/07",
    "numero_facture": "FC-06310-2212",
    "civilite": "Monsieur",
    "prenom": "Léon",
    "nom": "Zitrone"
  },
  "fichier_annexes": [
    {
      "url": "https://sandbox-example-file.servicepostal.com/0b6a550f495f9d38500c4af1f3a5a1c0_01-01-2666.pdf"
    }
  ],
  "type_affranchissement": "lrar",
  "couleur": "nb",
  "recto_verso": "rectoverso",
  "placement_adresse": "insertion_page_adresse",
  "surimpression_adresses_document": true,
  "ar_scan": true,
  "ar_expediteur_champ1": "Référence : CL-06310/07",
  "ar_expediteur_champ2": "Facture : FC-06310-2212",
  "code_barre": true,
  "affranchissement": "6.15",
  "service": "2.47",
  "total": "8.62",
  "affranchissement_base": "6.15",
  "service_base": "2.47",
  "total_base": "8.62"
}

Changes

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