> For the complete documentation index, see [llms.txt](https://academy.cegedim.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.cegedim.cloud/francais/message/sms/envoyer-un-sms-avec-lapi.md). # SMS - Envoyer avec l'API Cette page détaille la requête d'envoi de SMS (`POST /sms`), avec des exemples JSON complets et la liste des codes retour et payloads d'erreur possibles. Pour l'authentification, l'URL de base et le format général des requêtes, voir [SMS - Didacticiels](/francais/message/sms/sms-didacticiels.md). {% hint style="warning" %} Envoyer une requête avec succès ne garantit pas la livraison du SMS. La requête est acceptée de manière synchrone, mais le SMS est délivré de manière asynchrone au terminal du destinataire. Utilisez la requête de consultation du statut d'un SMS pour vérifier sa livraison. {% endhint %} ## Requête ``` POST /sms Content-Type: application/json Authorization: Basic ``` ### Corps de la requête | Champ | Type | Requis | Description | | -------------- | ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `phoneNumber` | string | Oui | Numéro du destinataire : soit un numéro local français (10 chiffres), soit un numéro international au format `+`. | | `message` | string | Oui | Contenu du message, 600 caractères maximum. Un SMS est facturé tous les 160 caractères. | | `allowUnicode` | boolean | Non | `true` par défaut. Si `false`, force l'encodage GSM 03.38 au lieu d'unicode. | | `metadata` | object | Non | Objet JSON libre pour associer des données personnalisées au message (voir exemple ci-dessous). | ### Exemple simple ```json { "phoneNumber": "+33612345678", "message": "Please call me back" } ``` ### Exemple avec métadonnées personnalisées Le tag `metadata` ajouté est renvoyé lors de la consultation des détails du SMS. ```json { "phoneNumber": "+33612345678", "message": "Please call me back", "metadata": { "myCustomerId": "123de32", "caller": "MyApp 2.2" } } ``` ## Réponse en cas de succès Un envoi accepté renvoie `200` avec l'identifiant du message, à utiliser pour consulter son statut de livraison par la suite. ```json { "messageId": "77a76363bd882992893", "smsCount": 1 } ``` ## Codes retour et erreurs possibles Le format du corps d'erreur dépend du contrôle qui a rejeté la requête - il n'y a pas de format unifié entre les différents codes retour. | Code | Signification | | ----- | --------------------------------------------------------------------------------------------- | | `200` | SMS accepté pour envoi. | | `400` | Requête invalide (champ manquant/trop long, numéro non reconnu, ou rejet du fournisseur SMS). | | `422` | Destinataire non autorisé pour ce compte (voir ci-dessous). | | `429` | Seuil de débit (SMS/minute ou SMS/heure) atteint pour ce compte. | | `503` | Aucun fournisseur SMS disponible actuellement - à retenter plus tard. | ### `400` Bad Request Trois situations distinctes renvoient `400`, avec trois formats de corps différents : * Un champ manquant/vide, ou un `message` de plus de 600 caractères, échoue à la validation de champ. Le corps est une correspondance clé/valeur, une entrée par champ invalide : ```json { "message": "length must be between 1 and 600" } ``` * Un `phoneNumber` qui ne peut pas être analysé comme un numéro valide (format incorrect, indicatif de pays inconnu, caractères non numériques...) échoue à un contrôle ultérieur, une fois la validation de champ passée. Le corps n'a qu'une clé `error`, dont la valeur est le `phoneNumber` envoyé, tel quel : ```json { "error": "+33 6 not-a-number" } ``` * Si la configuration du fournisseur SMS de votre compte rejette elle-même la requête (par exemple un `fromName` invalide), le corps est un tableau de causes : ```json [ { "code": "INVALID_MESSAGE_LENGTH", "on": "message", "message": "Message length cannot exceed 600 characters" } ] ``` ### `422` Unprocessable Entity Le destinataire n'est pas autorisé pour votre compte. Ceci couvre trois politiques indépendantes configurables par compte : une liste blanche de pays de destination, une liste noire de pays de destination, et une liste blanche de numéros de téléphone. Les trois produisent le même corps - la réponse n'indique pas laquelle s'est déclenchée. C'est un `422`, pas un `403` : vos identifiants et votre rôle sont valides, c'est spécifiquement le destinataire de cette requête que la politique de votre compte rejette. ```json { "error": "RECIPIENT_NOT_ALLOWED" } ``` Aucun SMS n'est envoyé et aucune tentative de livraison n'a lieu dans ce cas. {% hint style="info" %} Si une liste blanche de pays contient au moins une entrée, elle prend systématiquement le pas sur la liste noire de pays, qui est alors ignorée pour ce compte. {% endhint %} ### `429` Too Many Requests Renvoyé lorsque le seuil de débit (SMS/minute ou SMS/heure) de votre compte est atteint. Le format du corps correspond au cas de rejet par le fournisseur SMS ci-dessus (un tableau de causes) - notez que `message` est un template générique non interpolé ici (le `%s` littéral n'est pas une erreur), le détail réel (quel seuil, combien de SMS) se trouve dans `args` : ```json [ { "code": "LIMIT_REACHED", "message": "Request cannot be completed because of limit [%s]", "args": ["Threshold of 10 SMS within a minute has been reached."] } ] ``` ### `503` Service Unavailable Aucun fournisseur SMS n'est actuellement disponible pour envoyer votre message - à retenter plus tard, en suivant le pattern décrit ci-dessous. ```json { "error": "No providers are currently available to send SMS, retry later" } ``` ## Pattern client recommandé Vortext peut avoir jusqu'à 5 secondes d'indisponibilité en cas de défaillance d'un nœud de notre infrastructure clusterisée. Dans ce cas, vous obtiendrez une erreur `502` ou `503`. Pour garantir la délivrance du message, envisagez d'appeler le service avec ce pattern : ``` sendSms(); if (échec) { attendre(5 secondes); sendSms(); if (échec) { ceciEstUnVraiEchec(); } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://academy.cegedim.cloud/francais/message/sms/envoyer-un-sms-avec-lapi.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.