API Postilis · v1
Démarrage rapide
Envoyez un vrai courrier postal depuis votre logiciel, à partir d’un PDF, en un seul appel.
Un seul appel
PDF + destinataire → courrier imprimé, mis sous pli et posté.
Jamais de double envoi
Clé d’idempotence obligatoire : rejouer une requête ne renvoie jamais le courrier.
Mode test complet
Clés de test : tout le parcours simulé, sans courrier ni paiement.
Suivi en temps réel
Webhooks signés à chaque étape : validé, imprimé, posté.
L’API Postilis permet à votre logiciel (facturation, gestion, CRM…) d’envoyer une lettre simple en France métropolitaine et en Corse : Postilis imprime votre PDF, le met sous pli avec une page porte-adresse (offerte) et le remet à La Poste. Vous payez au prix de la grille tarifaire, avec votre crédit prépayé, et chaque envoi reçoit sa facture.
- •Adresse de l’API : https://postilis.fr/api/v1
- •Format : JSON en UTF-8 ; montants en centimes d’euro TTC ; dates au format RFC 3339.
- •Réservée aux professionnels : compte professionnel avec numéro SIREN et adresse e-mail confirmée.
En cinq minutes
1
Créez une clé de test
Dans Mon compte → API et crédit prépayé, créez une clé en mode « Test ». Elle commence par pst_test_ et ne sera affichée qu’une fois.
2
Ajoutez du crédit de test
En mode test, le crédit est fictif et ajouté immédiatement.
cURL
Node.js
PHP
Python
curl https://postilis.fr/api/v1/balance/topups \
-H "Authorization: Bearer $POSTILIS_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{"amount_cents": 10000}'
3
Envoyez votre premier courrier
Un seul appel POST /letters : la description de l’envoi (partie « letter ») et le PDF (partie « file »).
cURL
Node.js
PHP
Python
curl https://postilis.fr/api/v1/letters \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Idempotency-Key: facture-2026-0042" \
-F 'letter={"recipient":{"full_name":"Marie Durand","street":"8 boulevard du Port","postal_code":"80000","city":"Amiens"},"duplex":true}' \
-F "file=@facture-2026-0042.pdf;type=application/pdf"
Réponse 201
{
"id": "0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f",
"reference": "PST-7K3M9Q",
"status": "processing",
"livemode": true,
"recipient": {
"full_name": "Marie Durand", "company": "", "complement": "Bâtiment B",
"street": "8 boulevard du Port", "locality": "", "postal_code": "80000",
"city": "Amiens", "country_code": "FR"
},
"document": { "filename": "facture-2026-0042.pdf", "pages": 2, "available": true },
"postage": "simple",
"color": false,
"duplex": true,
"pages": 2,
"price_cents": 330,
"currency": "EUR",
"paid_with": "balance",
"tracking_number": null,
"estimated_delivery": null,
"invoice_available": true,
"credit_note_available": false,
"created_at": "2026-09-28T09:14:02Z",
"paid_at": "2026-09-28T09:14:03Z",
"printed_at": null,
"in_transit_at": null,
"delivered_at": null,
"refunded_at": null
}
4
Suivez l’envoi
Déclarez une adresse de webhook : votre logiciel est prévenu quand le courrier est imprimé puis remis aux services postaux. En mode test, ces étapes s’enchaînent en quelques secondes.
5
Passez en réel
Rechargez votre crédit, créez une clé pst_live_ et remplacez la clé de test : le code ne change pas.
Authentification
Chaque requête porte votre clé dans l’en-tête Authorization :
En-tête
Authorization: Bearer pst_live_3fa9…c2d1
- •pst_test_… : mode test (bac à sable) ; pst_live_… : envois réels. Les deux modes sont totalement séparés : un envoi de test n’est visible qu’avec une clé de test.
- •Gardez vos clés côté serveur (jamais dans une application mobile ou une page web) et stockez-les comme des mots de passe (variable d’environnement, coffre-fort de secrets).
- •Une clé compromise se révoque en un clic dans votre compte : elle cesse aussitôt de fonctionner.
- •Une clé permet d’envoyer, suivre et payer des courriers, de gérer le carnet d’adresses et de télécharger les factures. La gestion du compte, des clés et des webhooks se fait uniquement dans l’application Postilis.
Idempotence : la règle d’or
Un courrier coûte de l’argent et ne s’annule pas. Envoyez toujours un en-tête Idempotency-Key unique par courrier (numéro de facture, UUID…) et, en cas de doute (coupure réseau, délai dépassé), renvoyez la même requête : Postilis renvoie l’envoi déjà créé au lieu d’en créer un second.
Prêt à commencer ?
Créez un compte professionnel, puis une clé de test : essayez l’API sans envoyer de courrier ni payer.