API Postilis · v1
Crédit et mode test
Payez vos envois avec un crédit prépayé, et développez sans risque grâce au bac à sable.
Crédit prépayé
Les envois commandés par l’API sont payés avec votre crédit prépayé, sans intervention humaine. Vous le rechargez par carte bancaire, sur notre page de paiement sécurisé, depuis votre compte ou par l’API.
- •Chaque envoi débite son prix TTC, une seule fois, et donne lieu à une facture (téléchargeable par GET /orders/{id}/invoice).
- •Un envoi qui ne peut pas être expédié est recrédité automatiquement, avec un avoir.
- •Recharge de 10 € à 2 000 € ; crédit total de 5 000 € au plus.
- •Le crédit non utilisé peut être remboursé à tout moment sur la carte qui l’a payé, depuis votre compte (« Récupérer mon crédit »).
GET
/balance
Réponse 200
{
"balance_cents": 4710,
"currency": "EUR",
"livemode": true,
"min_topup_cents": 1000,
"max_topup_cents": 200000,
"max_balance_cents": 500000
}
POST
/balance/topups
En mode réel, la réponse contient checkout_url : la page de paiement sécurisé, à ouvrir par une personne (aucune donnée de carte ne transite par l’API ni par Postilis). Le crédit est ajouté dès la confirmation du paiement ; vous en êtes prévenu par l’événement balance.credited.
Mouvements (GET /balance/transactions)
topup
+
Recharge créditée.
order_payment
−
Paiement d’un envoi.
order_refund
+
Recrédit d’un envoi qui n’a pas pu être expédié.
withdrawal
−
Remboursement du crédit sur votre carte.
Anticiper
Surveillez votre crédit (GET /balance) et rechargez avant qu’il ne s’épuise : un envoi sans crédit suffisant est refusé (402 insufficient_balance), sans débit, et peut être relancé tel quel après la recharge.
Mode test
Avec une clé pst_test_…, toutes les routes fonctionnent comme en réel — mêmes contrôles, mêmes prix, mêmes réponses, mêmes webhooks — mais dans un bac à sable totalement séparé :
- •aucun courrier n’est imprimé ni posté, aucun paiement n’a lieu, aucune facture n’est émise ;
- •les références commencent par TST- et les envois portent "livemode": false ;
- •le crédit de test est fictif : une recharge est créditée immédiatement ;
- •les envois de test ne sont visibles qu’avec une clé de test (et conservés 90 jours) ; le carnet d’adresses est commun aux deux modes : une clé de test peut le lire et y ajouter des destinataires, mais pas modifier ni supprimer un destinataire, ni télécharger ou supprimer un document (réponse 403 forbidden).
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}'
Scénarios simulés
Après le paiement, un envoi de test franchit une étape toutes les 15 secondes environ. Le nom ou la société du destinataire choisit le scénario :
(par défaut)
succès
processing → printed → in_transit (avec date de distribution estimée).
[refus]
échec
processing → refunded : le prix est recrédité sur le crédit de test.
[retour]
retour
processing → printed → in_transit → returned.
[distribue]
distribué
processing → printed → in_transit → delivered.
Exemple : un destinataire nommé Marie Durand [refus] permet de tester le traitement d’un remboursement dans votre logiciel.
Passer en production
Remplacez la clé de test par une clé pst_live_, déclarez une adresse de webhook « réelle » et rechargez votre crédit : votre code ne change pas.