--- title: "Envoyer un SMS ou un courrier" description: "Prévisualiser, chiffrer et envoyer une relance payante sans créer de doublon." canonical: https://developer.billabex.com/fr/guides/messages-sortants/ lang: fr alternate: https://developer.billabex.com/en/guides/outgoing-messages/ last-updated: 2026-10-11 --- # Envoyer un SMS ou un courrier > Prévisualiser, chiffrer et envoyer une relance payante sans créer de doublon. Source: https://developer.billabex.com/fr/guides/messages-sortants/ Langue: Français (fr) Version anglaise: https://developer.billabex.com/en/guides/outgoing-messages/ L'API publique permet d'envoyer un SMS, un courrier suivi ou un recommandé avec avis de réception. Ces envois consomment des crédits et ne peuvent pas être rappelés. Le flux recommandé est donc: 1. prévisualiser le message et son coût; 2. fixer `maxCredits` au coût accepté; 3. envoyer avec une `idempotencyKey` stable; 4. relire la communication pour suivre sa livraison. Tous les endpoints de cette page utilisent le scope OAuth `dunning:manage`. La lecture d'une communication accepte aussi `communications:read`. ## Tarification | Canal | Coût | | ------------------ | ------------------------------------------------------- | | `Sms` | 1 crédit par segment, selon l'encodage GSM-7 ou Unicode | | `TrackedLetter` | 6 crédits, plus 1 crédit par page après la première | | `RegisteredLetter` | 12 crédits, plus 1 crédit par page après la première | Le serveur calcule toujours le coût à partir du contenu final. Un SMS long peut occuper plusieurs segments. Les factures et les avoirs joints au courrier augmentent son nombre de pages. ## Prévisualiser ```http POST https://next.billabex.com/api/public/v1/accounts/ACCOUNT_ID/outgoing-message-communications/preview Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` Exemple SMS: ```json { "channel": "Sms", "contactId": "CONTACT_ID", "recipientPhone": "+33612345678", "invoiceIds": ["INVOICE_ID"], "paymentDeadline": "2026-08-25" } ``` Exemple courrier: ```json { "channel": "RegisteredLetter", "invoiceIds": ["INVOICE_ID"], "creditNoteIds": [], "paymentDeadline": "2026-08-25", "recipientAddress": { "fullName": "Client SA", "street": "1 rue de la Paix", "postalCode": "75001", "city": "Paris", "country": "FR" }, "includePdf": true } ``` La réponse ne débite aucun crédit: ```json { "pdfBase64": null, "html": "", "body": "Votre message final", "pageCount": 0, "credits": 1 } ``` Pour un SMS, `pageCount` vaut `0`, `html` est vide et `pdfBase64` vaut `null`. Pour un courrier, `pageCount` inclut les annexes. `includePdf: true` assemble le dossier complet dans `pdfBase64`. ## Envoyer sans doublon ```http POST https://next.billabex.com/api/public/v1/accounts/ACCOUNT_ID/outgoing-message-communications Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` Reprenez les mêmes champs que pour l'aperçu et ajoutez les deux garde-fous: ```json { "channel": "Sms", "contactId": "CONTACT_ID", "recipientPhone": "+33612345678", "invoiceIds": ["INVOICE_ID"], "paymentDeadline": "2026-08-25", "idempotencyKey": "account-123-invoice-456-sms-2026-08-25", "maxCredits": 1 } ``` `idempotencyKey` est facultative dans l'API, mais toute intégration automatisée doit la fournir. Billabex en dérive l'identifiant de communication. Rejouer la même clé dans l'organisation renvoie la communication déjà enregistrée, sans nouveau débit et sans nouvel appel au prestataire. Une même clé doit toujours désigner la même intention d'envoi. Utilisez une nouvelle clé pour un nouveau destinataire, un nouveau contenu ou une nouvelle échéance. `maxCredits` est facultatif. Si le rendu coûte davantage, l'API refuse avant tout débit et renvoie un `400`. Fixez-le de préférence à la valeur `credits` obtenue lors de l'aperçu. Limite connue: deux requêtes strictement concurrentes avec la même clé peuvent toutes deux franchir la lecture initiale avant l'enregistrement de la première communication. Ne parallélisez pas vos propres rejeux. ## Relire la livraison ```http GET https://next.billabex.com/api/public/v1/accounts/ACCOUNT_ID/outgoing-message-communications/COMMUNICATION_ID Authorization: Bearer YOUR_ACCESS_TOKEN ``` La réponse contient notamment `channel`, `creditsCharged`, `deliveryStatus` et `statusHistory`. Les webhooks des prestataires restent internes à Billabex. Interrogez cet endpoint pour obtenir le dernier état connu. Le GET et l'outil MCP `get-communication` (sous `message`) renvoient aussi `pdfUrl`, un lien signé vers le PDF réellement envoyé, annexes comprises. Il vaut `null` pour un SMS ou une archive indisponible. Le lien expire après 15 minutes : relisez le détail pour en obtenir un nouveau. ### Suivi postal détaillé `postalTracking` contient `checkedAt` (dernière vérification réussie), `reference` (Merci Facteur), `status` (traitement fournisseur) et `steps`. Chaque étape expose `date` (`YYYY-MM-DD` ou `null`), `time` (heure locale du fournisseur ou `null`) et `label`. Ne transformez pas une date seule en heure de livraison. `acknowledgementUrl` donne un lien signé de 15 minutes vers l'accusé de réception numérisé lorsqu'il est disponible ; sinon il vaut `null`. ```http POST https://next.billabex.com/api/public/v1/accounts/ACCOUNT_ID/outgoing-message-communications/COMMUNICATION_ID/refresh-tracking Authorization: Bearer YOUR_ACCESS_TOKEN ``` Sans corps. Autorisations : `communications:read` ou `dunning:manage`. La réponse `201` contient le détail actualisé, y compris les liens de fichiers. Cette opération ne renvoie aucun courrier et ne débite aucun crédit. Une vérification réussie de moins d'une minute est réutilisée. L'outil MCP `refresh-outgoing-message-tracking` accepte `communicationId` et demande `mcp:write`. ## Erreurs | Statut | Signification | | ------ | -------------------------------------------------------------------------- | | `400` | Sélection, destinataire, adresse, coordonnées courrier ou plafond invalide | | `402` | Solde de crédits insuffisant | | `404` | Compte ou communication introuvable | | `502` | Résultat du prestataire inconnu ou échec d'envoi | Un `400` porte toujours un champ `code` stable, à préférer au message pour brancher votre code. Un dépassement de plafond renvoie `app-dunning.outgoing-message-communication.maximum-credits-exceeded` et un objet `details` contenant `credits`, le coût réel du rendu, et `maxCredits`, la limite que vous aviez fixée : vous pouvez donc décider de relancer avec un plafond relevé sans refaire d'aperçu. Quand le résultat du prestataire est inconnu, les crédits restent débités car le message a pu être accepté. Ne recommencez pas avec une autre clé. Les coordonnées nécessaires au courrier se configurent avec `PUT /api/public/v1/organizations/:organizationId/settings`, dans `letterDetails`. ## MCP Le serveur MCP expose le même flux: | Outil | Scope | Rôle | | -------------------------- | ----------- | ------------------------------------------ | | `preview-outgoing-message` | `mcp:read` | Calculer le contenu et le coût | | `send-outgoing-message` | `mcp:write` | Envoyer avec une clé obligatoire | | `get-communication` | `mcp:read` | Relire le message et son état de livraison | Par défaut, l'aperçu MCP ne renvoie ni PDF base64 ni HTML ; passez `includePdf: true` pour ajouter `pdfBase64` et `html` à l'aperçu d'un courrier, qui sont volumineux. `send-outgoing-message` couvre les SMS et les courriers, exige `idempotencyKey` et annonce explicitement son coût et son caractère irréversible. `get-communication` prend le `communicationId` et le `type` du message (`OutgoingSms`, `OutgoingTrackedLetter` ou `OutgoingRegisteredLetter`) et renvoie le message sous `message`. Les anciens endpoints REST `/outgoing-letters` restent disponibles pour les intégrations existantes, mais sont dépréciés. --- Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json. Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.