API Postilis · v1
Envoyer un courrier
En un seul appel, ou en plusieurs étapes pour les gros fichiers — sans jamais risquer un double envoi.
En un seul appel
POST
/letters
Formulaire multipart/form-data à deux parties : `letter`, la description de l’envoi en JSON, et `file`, le PDF. Postilis contrôle le document, crée l’envoi, le paie avec votre crédit prépayé et répond 201 avec l’envoi (objet Order) au statut processing.
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"
Partie « letter » (JSON)
recipient
Address
Adresse du destinataire : full_name ou company, complement, street, locality, postal_code, city. Exactement un de recipient ou recipient_id.
recipient_id
uuid
Un destinataire de votre carnet d’adresses.
duplex
booléen
Recto verso (moins de feuilles, prix souvent plus bas). Par défaut : recto seul.
save_recipient
booléen
Ajoute le destinataire à votre carnet d’adresses.
recipient_label
texte
Libellé dans le carnet (avec save_recipient).
En-têtes
Authorization
Bearer pst_…
obligatoire
Votre clé d’API.
Idempotency-Key
texte (1 à 255)
obligatoire
Valeur unique par courrier (voir ci-dessous).
Le document PDF
- •Format A4, en portrait ou en paysage, 100 pages et 100 Mo au plus, sans mot de passe.
- •L’adresse n’a pas besoin de figurer dans votre PDF : Postilis ajoute toujours en tête une page porte-adresse, visible par la fenêtre de l’enveloppe. Elle est offerte : jamais comptée dans le nombre de pages ni dans le prix.
- •Impression en noir et blanc, en recto seul ou en recto verso ; lettre simple, distribuée en 4 jours ouvrables environ après la remise aux services postaux.
- •Votre adresse postale (renseignée dans votre compte) est transmise comme expéditeur, sans être imprimée sur le courrier.
- •Le PDF n’est pas conservé : il est supprimé dès sa prise en charge pour impression (ou au bout de 24 heures s’il n’est pas envoyé). Seuls son empreinte et son nombre de pages sont gardés.
Ne jamais envoyer deux fois le même courrier
L’en-tête Idempotency-Key est obligatoire sur POST /letters. Choisissez une valeur liée au courrier lui-même, par exemple facture-2026-0042 ou un UUID enregistré avec la facture dans votre base.
Première requête
Réponse de Postilis : 201 : l’envoi est créé et payé.
Même clé, même contenu (requête rejouée)
Réponse de Postilis : 200 : l’envoi existant, en-tête Idempotent-Replayed: true. Aucun second courrier.
Même clé, crédit insuffisant la première fois
Réponse de Postilis : L’envoi en attente est payé à cette occasion (200).
Même clé, autre contenu
Réponse de Postilis : 422 idempotency_key_reused : rien n’est créé.
Bonne pratique
Après une coupure réseau, une erreur 500 ou un délai dépassé, vous ne savez pas si le courrier a été créé : renvoyez simplement la même requête avec la même clé. C’est sans risque.
Crédit insuffisant
Si votre crédit ne couvre pas l’envoi, Postilis répond 402 insufficient_balance et rien n’est débité. L’envoi reste en attente (le PDF est gardé 24 heures) : rechargez votre crédit puis renvoyez la même requête. Vous pouvez surveiller votre crédit avec GET /balance ou l’événement balance.credited.
En plusieurs étapes
Pour les gros fichiers (envoi par morceaux avec reprise), ou pour connaître le prix exact avant de payer :
1.
POST
/documents
Réservez le document ({filename, size_bytes}) : la réponse contient les instructions « upload ».
2.
PUT
/documents/{id}/content
Envoyez les octets du PDF à l’adresse upload.url (ou par morceaux : upload.parts).
3.
POST
/documents/{id}/complete
Postilis contrôle le PDF et compte ses pages.
4.
POST
/orders
Créez le brouillon : il indique son prix (price_cents).
5.
POST
/orders/{id}/pay
Payez avec le crédit : l’envoi part.
Exemple (cURL)
# 1. Réserver le document
curl https://postilis.fr/api/v1/documents -H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" -d '{"filename":"devis.pdf","size_bytes":182734}'
# 2. Envoyer le fichier (adresse upload.url de la réponse précédente)
curl -X PUT "https://postilis.fr/api/v1/documents/$DOC_ID/content" -H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/pdf" --data-binary @devis.pdf
# 3. Contrôler le PDF
curl -X POST https://postilis.fr/api/v1/documents/$DOC_ID/complete -H "Authorization: Bearer $POSTILIS_API_KEY"
# 4. Créer le brouillon (prix dans price_cents)
curl https://postilis.fr/api/v1/orders -H "Authorization: Bearer $POSTILIS_API_KEY" -H "Content-Type: application/json" \
-d '{"document_id":"'$DOC_ID'","recipient_id":"7d1e6a38-5b5e-4c1b-8f0d-6f3f1c1a0001","duplex":true}'
# 5. Payer avec le crédit
curl -X POST https://postilis.fr/api/v1/orders/$ORDER_ID/pay -H "Authorization: Bearer $POSTILIS_API_KEY"
Envoi par morceaux : si upload.parts est présent, envoyez le morceau n (de 1 à part_count, de part_size octets sauf le dernier) par PUT upload.parts.url + n. Après une coupure, GET /documents/{id}/parts liste les morceaux reçus : ne renvoyez que les manquants, puis appelez complete. Détail de chaque route dans la référence.