Envoyer un SMS ou un courrier

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

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

POST [baseURL]/api/public/v1/accounts/ACCOUNT_ID/outgoing-message-communications/preview
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Exemple SMS:

{
  "channel": "Sms",
  "contactId": "CONTACT_ID",
  "recipientPhone": "+33612345678",
  "invoiceIds": ["INVOICE_ID"],
  "paymentDeadline": "2026-08-25"
}

Exemple courrier:

{
  "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:

{
  "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

POST [baseURL]/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:

{
  "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

GET [baseURL]/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.

Erreurs

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:

L’aperçu MCP ne renvoie ni PDF base64 ni HTML. send-outgoing-message exige idempotencyKey et annonce explicitement son coût et son caractère irréversible.

Les anciens endpoints /outgoing-letters et les outils preview-outgoing-letter / send-outgoing-letter restent disponibles pour les intégrations existantes, mais sont dépréciés.