API Postilis · v1
Référence de l’API
Toutes les routes accessibles avec une clé d’API, leurs paramètres, leurs réponses et leurs erreurs.
Adresse de base : https://postilis.fr/api/v1. Authentification : Authorization: Bearer <clé> (sauf mention contraire). Corps JSON (Content-Type: application/json), sauf POST /letters (multipart) et l’envoi des fichiers. La spécification OpenAPI 3.1 est disponible à l’adresse https://postilis.fr/openapi.yaml (Postman, Insomnia, générateurs de clients…).
Sommaire
Envois
POST
/letters
Envoyer un courrier en un seul appel
GET
/orders
Lister les envois
GET
/orders/{id}
Consulter un envoi
POST
/orders
Créer un brouillon
PATCH
/orders/{id}
Modifier un brouillon
POST
/orders/{id}/pay
Payer un brouillon avec le crédit
POST
/orders/{id}/cancel
Annuler un brouillon
GET
/orders/{id}/invoice
Télécharger la facture
GET
/orders/{id}/credit-note
Télécharger l’avoir
Documents
POST
/documents
Réserver un document
PUT
/documents/{id}/content
Envoyer le fichier
PUT
/documents/{id}/parts/{n}
Envoyer un morceau
GET
/documents/{id}/parts
Morceaux reçus
POST
/documents/{id}/complete
Contrôler le fichier reçu
GET
/documents/{id}
Consulter un document
DELETE
/documents/{id}
Supprimer un document
Crédit prépayé
GET
/balance
Consulter le crédit
GET
/balance/transactions
Mouvements du crédit
POST
/balance/topups
Recharger le crédit
GET
/balance/topups/{id}
Consulter une recharge
Carnet d’adresses
GET
/recipients
Lister les destinataires
POST
/recipients
Ajouter un destinataire
GET
/recipients/{id}
Consulter un destinataire
PUT
/recipients/{id}
Modifier un destinataire
DELETE
/recipients/{id}
Supprimer un destinataire
POST
/addresses/validate
Vérifier une adresse
GET
/addresses/search
Autocompléter une adresse
Compte et service
GET
/me
Compte de la clé
GET
/pricing
Grille tarifaire
GET
/status
État du service
Objets : Order, Address, Document, BalanceTransaction →
Envois
Créer, payer et suivre des courriers. Avec une clé de test, ces routes agissent sur le bac à sable.
POST
/letters
Envoyer un courrier en un seul appel
Téléverse le PDF, crée l’envoi et le paie avec votre crédit prépayé. Formulaire multipart/form-data : partie « letter » (JSON) et partie « file » (PDF). Rejouer la même requête avec la même Idempotency-Key renvoie l’envoi existant (200) ; si le crédit manquait, l’envoi est alors payé.
Idempotency-Key obligatoire
Corps de la requête
letter
JSON
obligatoire
Description de l’envoi : champs ci-dessous.
letter.recipient
Address
Adresse du destinataire (voir l’objet Address). Exactement un de recipient ou recipient_id.
letter.recipient_id
uuid
Destinataire de votre carnet d’adresses (copie figée au moment de l’envoi).
letter.duplex
booléen
Impression recto verso (par défaut : recto seul).
letter.color
booléen
Impression couleur : non proposée pour l’instant (false).
letter.save_recipient
booléen
Ajoute aussi le destinataire à votre carnet d’adresses.
letter.recipient_label
texte
Libellé dans le carnet (avec save_recipient).
file
PDF
obligatoire
Format A4, 100 pages et 100 Mo au plus, sans mot de passe.
Requête (cURL)
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 Created · Order
{
"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
}
GET
/orders
Lister les envois
Du plus récent au plus ancien (brouillons annulés et expirés exclus).
Paramètres
limit
entier (requête)
Nombre d’éléments (20 par défaut, 50 au plus).
cursor
texte (requête)
Valeur next_cursor de la page précédente.
Requête (cURL)
curl "https://postilis.fr/api/v1/orders?limit=20" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK
{ "items": [ { …Order } ], "next_cursor": "0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" }
GET
/orders/{id}
Consulter un envoi
Statut, dates de chaque étape, date de distribution estimée, disponibilité de la facture.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl "https://postilis.fr/api/v1/orders/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK · Order
{
"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
}
Erreurs possibles :
not_found
POST
/orders
Créer un brouillon
Envoi en plusieurs étapes : à partir d’un document déjà téléversé et contrôlé. Le brouillon indique son prix (price_cents) ; il se paie avec POST /orders/{id}/pay.
Idempotency-Key facultative
Corps de la requête
document_id
uuid
obligatoire
Document au statut ready.
recipient
Address
Adresse du destinataire (voir l’objet Address). Exactement un de recipient ou recipient_id.
recipient_id
uuid
Destinataire de votre carnet d’adresses (copie figée au moment de l’envoi).
duplex
booléen
Impression recto verso (par défaut : recto seul).
color
booléen
Impression couleur : non proposée pour l’instant (false).
save_recipient
booléen
Ajoute aussi le destinataire à votre carnet d’adresses.
recipient_label
texte
Libellé dans le carnet (avec save_recipient).
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/orders" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Idempotency-Key: brouillon-2026-0042" \
-H "Content-Type: application/json" \
-d '{ "document_id": "5c1d9a7e-2b44-4e0f-8f5a-1d2c3b4a5f6e", "recipient_id": "7d1e6a38-5b5e-4c1b-8f0d-6f3f1c1a0001", "duplex": true }'
Réponse : 201 Created · Order (draft)
PATCH
/orders/{id}
Modifier un brouillon
Change le destinataire ou les options ; le prix est recalculé.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Corps de la requête
recipient
Address
Adresse du destinataire (voir l’objet Address). Exactement un de recipient ou recipient_id.
recipient_id
uuid
Destinataire de votre carnet d’adresses (copie figée au moment de l’envoi).
duplex
booléen
Impression recto verso (par défaut : recto seul).
color
booléen
Impression couleur : non proposée pour l’instant (false).
save_recipient
booléen
Ajoute aussi le destinataire à votre carnet d’adresses.
recipient_label
texte
Libellé dans le carnet (avec save_recipient).
Requête (cURL)
curl -X PATCH "https://postilis.fr/api/v1/orders/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "duplex": false }'
Réponse : 200 OK · Order
Erreurs possibles :
invalid_state
POST
/orders/{id}/pay
Payer un brouillon avec le crédit
Débite votre crédit prépayé et lance l’envoi. Rejouer l’appel sur un envoi déjà payé renvoie l’envoi sans nouveau débit.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/orders/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/pay" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 200 OK · Order (processing)
POST
/orders/{id}/cancel
Annuler un brouillon
Seul un envoi non payé peut être annulé : un courrier payé part toujours.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/orders/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/cancel" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 200 OK · Order (cancelled)
Erreurs possibles :
invalid_state
GET
/orders/{id}/invoice
Télécharger la facture
PDF au format Factur-X (PDF/A-3 avec le fichier factur-x.xml, profil EN 16931). Mode réel uniquement.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl https://postilis.fr/api/v1/orders/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/invoice \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-o facture.pdf
Réponse : 200 OK · application/pdf
Erreurs possibles :
not_found
GET
/orders/{id}/credit-note
Télécharger l’avoir
Pour un envoi remboursé (credit_note_available : true).
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl "https://postilis.fr/api/v1/orders/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/credit-note" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 200 OK · application/pdf
Erreurs possibles :
not_found
Documents
Téléversement en plusieurs étapes, avec reprise pour les gros fichiers. Pour un envoi simple, préférez POST /letters.
POST
/documents
Réserver un document
Renvoie le document (pending_upload) et les instructions de téléversement : envoyez le fichier avec la méthode, l’adresse et les en-têtes de « upload ». Si upload.with_credentials vaut true, ajoutez aussi votre en-tête Authorization.
Corps de la requête
filename
texte
obligatoire
Nom du fichier (affiché dans vos envois).
size_bytes
entier
obligatoire
Taille exacte du fichier, en octets.
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/documents" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "filename": "facture-2026-0042.pdf", "size_bytes": 182734 }'
Réponse 201 Created
{
"document": { …Document (status "pending_upload") },
"upload": {
"method": "PUT",
"url": "https://postilis.fr/api/v1/documents/5c1d…/content",
"headers": { "Content-Type": "application/pdf" },
"with_credentials": true,
"expires_at": "2026-09-28T09:40:00Z",
"parts": { "part_size": 8388608, "part_count": 1,
"url": "https://postilis.fr/api/v1/documents/5c1d…/parts/",
"status_url": "https://postilis.fr/api/v1/documents/5c1d…/parts" }
}
}
PUT
/documents/{id}/content
Envoyer le fichier
Octets bruts du PDF (en-tête Content-Type: application/pdf). Utilisez l’adresse exacte renvoyée dans upload.url.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X PUT "https://postilis.fr/api/v1/documents/5c1d…/content" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/pdf" \
--data-binary @facture-2026-0042.pdf
Réponse : 204 No Content
PUT
/documents/{id}/parts/{n}
Envoyer un morceau
Envoi par morceaux avec reprise : le morceau n (de 1 à part_count) fait part_size octets, sauf le dernier. Après une coupure, GET /documents/{id}/parts indique les morceaux reçus.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
n
entier (chemin)
obligatoire
Numéro du morceau.
Requête (cURL)
curl -X PUT "https://postilis.fr/api/v1/documents/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/parts/1" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 204 No Content
Erreurs possibles :
bad_part
GET
/documents/{id}/parts
Morceaux reçus
Pour ne renvoyer que les morceaux manquants.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl "https://postilis.fr/api/v1/documents/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/parts" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK
{ "received": [1, 2], "part_count": 3 }
POST
/documents/{id}/complete
Contrôler le fichier reçu
Vérifie le PDF (format A4, pages, absence de mot de passe) et compte ses pages. Un document refusé est aussitôt supprimé.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/documents/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f/complete" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK · Document (ready)
{
"id": "5c1d9a7e-2b44-4e0f-8f5a-1d2c3b4a5f6e",
"filename": "facture-2026-0042.pdf",
"status": "ready",
"size_bytes": 182734,
"pages": 2,
"rejection_reason": null,
"expires_at": "2026-09-29T09:10:00Z",
"created_at": "2026-09-28T09:10:00Z"
}
GET
/documents/{id}
Consulter un document
Un document non envoyé est supprimé au bout de 24 heures ; un document envoyé, dès sa prise en charge pour impression.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl "https://postilis.fr/api/v1/documents/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK · Document
{
"id": "5c1d9a7e-2b44-4e0f-8f5a-1d2c3b4a5f6e",
"filename": "facture-2026-0042.pdf",
"status": "ready",
"size_bytes": 182734,
"pages": 2,
"rejection_reason": null,
"expires_at": "2026-09-29T09:10:00Z",
"created_at": "2026-09-28T09:10:00Z"
}
DELETE
/documents/{id}
Supprimer un document
Impossible pendant l’envoi (il est alors supprimé automatiquement après l’impression). Refusé avec une clé de test.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X DELETE "https://postilis.fr/api/v1/documents/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 204 No Content
Crédit prépayé
Le crédit du mode de la clé : réel (pst_live_) ou fictif (pst_test_).
GET
/balance
Consulter le crédit
Crédit disponible et bornes des recharges.
Requête (cURL)
curl "https://postilis.fr/api/v1/balance" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK
{
"balance_cents": 4710,
"currency": "EUR",
"livemode": true,
"min_topup_cents": 1000,
"max_topup_cents": 200000,
"max_balance_cents": 500000
}
GET
/balance/transactions
Mouvements du crédit
Recharges, envois, recrédits et remboursements sur carte, du plus récent au plus ancien.
Paramètres
limit
entier (requête)
20 par défaut, 100 au plus.
cursor
texte (requête)
Valeur next_cursor de la page précédente.
Requête (cURL)
curl "https://postilis.fr/api/v1/balance/transactions" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK
{
"items": [
{ "id": 12, "kind": "order_payment", "amount_cents": -330, "balance_after_cents": 4710,
"order_id": "0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f", "topup_id": null,
"description": "Envoi PST-7K3M9Q", "created_at": "2026-09-28T09:14:03Z" }
],
"next_cursor": null
}
POST
/balance/topups
Recharger le crédit
Mode réel : renvoie checkout_url, la page de paiement sécurisé à ouvrir par une personne ; le crédit est ajouté dès la confirmation du paiement (webhook balance.credited). Mode test : crédit fictif ajouté immédiatement.
Corps de la requête
amount_cents
entier
obligatoire
De 1 000 à 200 000 (10 € à 2 000 €) ; crédit total de 5 000 € au plus.
accept_terms
booléen
Acceptation des conditions générales de vente (obligatoire en mode réel).
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/balance/topups" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "amount_cents": 5000, "accept_terms": true }'
Réponse 201 Created · Topup
{
"id": "9e120d38-47f2-49cf-85f4-506eec406355",
"reference": "REC-8QW2MZ",
"livemode": true,
"amount_cents": 5000,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://…",
"refunded_cents": 0,
"expires_at": "2026-09-28T10:14:00Z",
"paid_at": null,
"created_at": "2026-09-28T09:14:00Z"
}
GET
/balance/topups/{id}
Consulter une recharge
Statut : pending, succeeded, expired ou cancelled. checkout_url n’est renseignée que pour une recharge en attente.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl "https://postilis.fr/api/v1/balance/topups/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 200 OK · Topup
Carnet d’adresses
Destinataires réutilisables (communs aux modes réel et test) et vérification des adresses.
GET
/recipients
Lister les destinataires
Triés par libellé (à défaut, par nom).
Requête (cURL)
curl "https://postilis.fr/api/v1/recipients" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK
{ "items": [ { "id": "7d1e6a38-…", "label": "Siège", …Address,
"created_at": "…", "updated_at": "…" } ] }
POST
/recipients
Ajouter un destinataire
Corps : les champs de l’objet Address, plus un libellé facultatif.
Corps de la requête
label
texte
Libellé (ex. « Siège »).
…
Address
obligatoire
Champs de l’adresse.
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/recipients" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Siège", "full_name": "Marie Durand", "street": "8 boulevard du Port", "postal_code": "80000", "city": "Amiens" }'
Réponse : 201 Created · Recipient
Erreurs possibles :
validation
GET
/recipients/{id}
Consulter un destinataire
Adresse et libellé.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl "https://postilis.fr/api/v1/recipients/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 200 OK · Recipient
PUT
/recipients/{id}
Modifier un destinataire
Les envois déjà créés gardent l’adresse d’origine. Refusé avec une clé de test.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X PUT "https://postilis.fr/api/v1/recipients/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Siège", "full_name": "Marie Durand", "street": "10 boulevard du Port", "postal_code": "80000", "city": "Amiens" }'
Réponse : 200 OK · Recipient
DELETE
/recipients/{id}
Supprimer un destinataire
Sans effet sur les envois existants. Refusé avec une clé de test.
Paramètres
id
uuid (chemin)
obligatoire
Identifiant.
Requête (cURL)
curl -X DELETE "https://postilis.fr/api/v1/recipients/0b8e2f4c-6f1d-4c1a-9d2e-3a5b7c9d1e2f" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 204 No Content
Erreurs possibles :
forbidden
POST
/addresses/validate
Vérifier une adresse
Nettoie et vérifie l’adresse (norme postale : 38 caractères par ligne, code postal de métropole ou de Corse) et renvoie les lignes imprimées sur la page porte-adresse (ville en majuscules, sans accents).
Requête (cURL)
curl -X POST "https://postilis.fr/api/v1/addresses/validate" \
-H "Authorization: Bearer $POSTILIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "full_name": "Marie Durand", "street": "8 bd du Port", "postal_code": "80000", "city": "amiens" }'
Réponse 200 OK
{
"address": { …Address normalisée },
"lines": ["Marie Durand", "8 bd du Port", "80000 AMIENS"]
}
Erreurs possibles :
validation
GET
/addresses/search
Autocompléter une adresse
Suggestions de la Base Adresse Nationale (métropole et Corse).
Paramètres
q
texte (requête)
obligatoire
Saisie en cours, ex. « 8 bd du port amiens ».
limit
entier (requête)
5 par défaut.
Requête (cURL)
curl "https://postilis.fr/api/v1/addresses/search?q=8%20bd%20du%20port%20amiens" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse 200 OK
{ "items": [ { "label": "8 Boulevard du Port 80000 Amiens", "street": "8 Boulevard du Port",
"postal_code": "80000", "city": "Amiens", "locality": "" } ] }
Compte et service
Informations générales.
GET
/me
Compte de la clé
Raison sociale, SIREN, adresse postale (transmise comme expéditeur, jamais imprimée) et api_access.
Requête (cURL)
curl "https://postilis.fr/api/v1/me" \
-H "Authorization: Bearer $POSTILIS_API_KEY"
Réponse : 200 OK · User
GET
/pricing
Grille tarifaire
Prix TTC par nombre de pages, en recto et en recto verso (grid). Sans authentification.
Sans authentification
Requête (cURL)
curl "https://postilis.fr/api/v1/pricing"
Réponse 200 OK
{ "currency": "EUR", "from_cents": 290, "max_pages": 100,
"grid": [ { "pages": 1, "recto_cents": 290, "recto_verso_cents": 290 }, … ] }
GET
/status
État du service
Indique si les nouveaux envois sont acceptés (sinon : erreur 503 orders_closed et message à afficher). Sans authentification.
Sans authentification
Requête (cURL)
curl "https://postilis.fr/api/v1/status"
Réponse 200 OK
{ "orders_open": true, "message": null, "test_mode": false }
Objets
Order
Un envoi (courrier).
id
uuid
Identifiant.
reference
texte
Référence lisible : PST-XXXXXX (réel), TST-XXXXXX (test). Imprimée sur la page porte-adresse.
status
texte
draft, processing, printed, in_transit, delivered, returned, refunded, cancelled ou expired.
livemode
booléen
false : envoi de test (jamais expédié ni facturé).
recipient
Address
Copie figée de l’adresse du destinataire.
document
objet
filename, pages, available (le PDF est supprimé après l’impression).
pages
entier
Pages de votre PDF (la page porte-adresse, offerte, n’est pas comptée).
duplex / color
booléens
Options d’impression.
price_cents
entier
Prix TTC en centimes.
paid_with
texte | null
balance (crédit prépayé) ou card ; null avant le paiement.
estimated_delivery
date | null
Date de distribution estimée (dès la remise aux services postaux).
tracking_number
texte | null
Numéro de suivi (lettres suivies, plus tard).
invoice_available / credit_note_available
booléens
Facture et avoir téléchargeables.
*_at
date-heure | null
created_at, paid_at, printed_at, in_transit_at, delivered_at, refunded_at.
Address
Adresse postale française (norme AFNOR NF Z10-011 : 38 caractères par ligne).
full_name
texte
Nom du destinataire (ou company).
company
texte
Raison sociale.
complement
texte
Appartement, bâtiment, service…
street
texte
obligatoire
Numéro et voie.
locality
texte
Lieu-dit.
postal_code
texte
obligatoire
5 chiffres (métropole et Corse).
city
texte
obligatoire
Commune.
country_code
texte
FR (par défaut).
Document
Un PDF téléversé.
status
texte
pending_upload, ready, rejected ou deleted.
pages
entier | null
Nombre de pages (après contrôle).
size_bytes
entier | null
Taille reçue.
rejection_reason
texte | null
Motif du refus, affichable tel quel.
expires_at
date-heure
Suppression automatique s’il n’est pas envoyé.
BalanceTransaction
Un mouvement du crédit prépayé.
kind
texte
topup (recharge), order_payment (envoi), order_refund (recrédit), withdrawal (remboursement sur carte).
amount_cents
entier
Montant signé (négatif pour un débit).
balance_after_cents
entier
Crédit après le mouvement.
order_id / topup_id
uuid | null
Envoi ou recharge concerné.