# Documentation Aureus Prime — API SMS d'Aureus Desk (texte complet) Source : https://docs.aureusprime.com Base de l'API : https://api.aureusprime.com/v1 --- # API SMS d'Aureus Desk Envoyez des **SMS transactionnels** — codes de connexion, confirmations de commande, rappels, alertes — vers les mobiles **MTN et Orange du Cameroun**, avec une API REST simple. Vous payez en FCFA, par recharge, et vous suivez chaque livraison. > **Démarrer en 5 minutes :** [créez votre clé d'API](https://docs.aureusprime.com/documentation/sms/compte-et-cle), puis envoyez votre premier SMS avec le [démarrage rapide](https://docs.aureusprime.com/documentation/sms/demarrage). ## Ce que vous pouvez faire | | | |---|---| | **[Envoyer un SMS](https://docs.aureusprime.com/documentation/sms/envoyer)** | Un appel, un SMS : 160 caractères (70 en Unicode), jamais coupés. | | **[Planifier un SMS](https://docs.aureusprime.com/documentation/sms/planifier)** | Choisissez la date d'envoi jusqu'à 30 jours à l'avance ; annulez, le crédit revient. | | **[Suivre la livraison](https://docs.aureusprime.com/documentation/sms/suivre)** | En file, envoyé, livré ou échec, avec la raison. Un refus rend le crédit. | | **[Consulter votre solde](https://docs.aureusprime.com/documentation/sms/solde-tarifs)** | Solde de crédits, alerte de solde bas, grille de prix et recharges. | | **[Votre nom d'expéditeur](https://docs.aureusprime.com/documentation/sms/expediteurs)** | Un nom commun tout de suite, ou le vôtre pour une organisation. | | **[Intégrer avec un assistant IA](https://docs.aureusprime.com/integration-ia/sms/assistants-ia)** | Un `AGENTS.md` prêt à coller pour que votre assistant de code utilise l'API correctement. | ## Liens utiles - **Espace Compte :** https://app.desk.aureusprime.com — vos clés d'API, vos envois, vos recharges. - **[Référence API](https://docs.aureusprime.com/reference/sms/routes)** — toutes les routes publiques. - **[Erreurs](https://docs.aureusprime.com/reference/sms/erreurs)** — codes stables et conduite à tenir. - **Texte complet pour les agents :** https://docs.aureusprime.com/llms-full.txt --- # Créer un compte et obtenir une clé d'API ## 1. Connectez-vous Ouvrez l'espace Compte d'Aureus Desk (https://app.desk.aureusprime.com) et connectez-vous avec votre **compte Aureus Prime** : une seule connexion pour tous les services Aureus. Choisissez d'agir en votre nom (particulier) ou au nom d'une organisation. ## 2. Faites vérifier votre compte Pour envoyer des SMS, il faut : - **particulier :** votre identité vérifiée (KYC) ; - **organisation :** votre entreprise vérifiée (KYB). La vérification se fait dans votre compte Aureus Prime. Tant qu'elle n'est pas faite, l'envoi répond `403 VERIFICATION_REQUIRED`. ## 3. Rechargez Une recharge se fait **en FCFA, à partir de 10 000** ; vous recevez le nombre de SMS du palier atteint (voir [Solde et recharges](https://docs.aureusprime.com/documentation/sms/solde-tarifs)). Pendant le pilote, la recharge se fait sur demande depuis l'espace Compte. ## 4. Créez une clé d'API Rubrique **Clés d'API** de l'espace Compte : 1. donnez un nom à la clé (par exemple « Site web ») ; 2. copiez la clé affichée — elle commence par `adk_sms_` et **ne sera plus jamais affichée** ; 3. rangez-la dans les variables d'environnement de votre serveur, par exemple `AUREUS_SMS_API_KEY`. Vous pouvez avoir **2 clés actives** au plus : la seconde sert à changer de clé sans coupure (voir [Authentification](https://docs.aureusprime.com/reference/sms/authentification)). ## Et ensuite Envoyez votre premier SMS avec le [démarrage rapide](https://docs.aureusprime.com/documentation/sms/demarrage). --- # Démarrage rapide L'API SMS d'Aureus Desk envoie des **SMS transactionnels** (codes de connexion, confirmations, rappels, alertes) vers les mobiles **MTN et Orange du Cameroun**, immédiatement ou à une date planifiée. Vous payez en FCFA, avec des crédits : **1 crédit = 1 SMS**. ## 1. Ouvrez un compte et faites-le vérifier Connectez-vous à l'espace Compte d'Aureus Desk (https://app.desk.aureusprime.com) avec votre compte Aureus Prime. Pour envoyer, votre identité (particulier) ou votre entreprise (organisation) doit être vérifiée dans votre compte Aureus Prime. ## 2. Créez une clé d'API Dans l'espace Compte, rubrique **Clés d'API**, créez une clé. Elle commence par `adk_sms_` et n'est affichée **qu'une seule fois** : copiez-la dans la configuration de votre serveur. Vous pouvez avoir **2 clés actives** au plus. ## 3. Envoyez votre premier SMS ```bash curl -X POST https://api.aureusprime.com/v1/sms/messages \ -H "Authorization: Bearer adk_sms_VOTRE_CLE" \ -H "Content-Type: application/json" \ -d '{"to": "699123456", "text": "Votre code est 482913"}' ``` Réponse `202` : le SMS est en file, un crédit est réservé. ```json { "id": "5b0f2c1e-8a4d-4f7e-9c3a-1d2b3c4d5e6f", "status": "QUEUED", "to": "+237*******56", "operator": "ORANGE", "senderId": "Aureus Desk", "errorCode": null, "scheduledAt": null, "createdAt": "2026-11-01T10:00:00.000Z", "sentAt": null, "deliveredAt": null, "likelyUndelivered": false } ``` Suivez ensuite sa livraison avec `GET /sms/messages/:id` (voir [Suivre un SMS](https://docs.aureusprime.com/documentation/sms/suivre)). ## L'essentiel à retenir - **Base de l'API :** `https://api.aureusprime.com/v1` - **Format :** JSON en entrée et en sortie, UTF-8. - **Texte :** 160 caractères en alphabet GSM, 70 dès qu'un caractère accentué hors GSM (ê, ô, ç, °…) ou un emoji apparaît ; un message plus long est refusé, jamais coupé. - **Numéros :** mobiles du Cameroun ; les numéros sont toujours masqués dans les réponses. - **Erreurs :** toujours la même forme, `{"error": {"code", "message"}}` (voir [Erreurs](https://docs.aureusprime.com/reference/sms/erreurs)). --- # Envoyer un SMS ```http POST https://api.aureusprime.com/v1/sms/messages ``` Met un SMS en file. Réponse `202`. Un crédit est réservé tout de suite ; il est consommé si le SMS est envoyé, rendu s'il est refusé avant l'envoi. ## Corps de la requête | Champ | Type | Obligatoire | Description | |---|---|---|---| | `to` | string | oui | Mobile du Cameroun : `699123456`, `+237 6 99 12 34 56`, `00237699123456` ou `237699123456` | | `text` | string | oui | 160 caractères en alphabet GSM, 70 dès qu'un caractère en sort (voir ci-dessous) | | `senderId` | string | non | Expéditeur validé de votre compte ; par défaut l'expéditeur commun | | `sensitive` | boolean | non | `true` pour un code ou un secret : texte effacé dès l'envoi, jamais conservé | | `scheduledAt` | string | non | Envoi planifié (voir [Planifier un SMS](https://docs.aureusprime.com/documentation/sms/planifier)) | **Longueur et encodage :** 1 crédit = 1 SMS, jamais coupé. **160 caractères** si le texte n'utilise que l'alphabet GSM (lettres sans accent, é è à ù, chiffres, ponctuation courante) ; `€ [ ] { } ^ ~ | \` y comptent pour 2. Dès qu'un seul caractère sort de cet alphabet (ê, ô, î, ç, « », °, ’, emoji), tout le SMS passe en Unicode et la limite tombe à **70 caractères** (un emoji compte pour 2). Au-delà : refus `422 TEXT_TOO_LONG`, jamais de coupure ni de SMS facturé plusieurs fois. Astuce : « no » plutôt que « n° », apostrophe droite `'` plutôt que `’`. ## En-tête facultatif : `Idempotency-Key` Envoyez la même clé (100 caractères visibles au plus) pour rejouer une demande sans nouveau débit : la réponse renvoie le même message, avec `"replayed": true`. Si la même clé sert pour un autre numéro ou un autre expéditeur : `409 IDEMPOTENCY_CONFLICT`. Voir [Bonnes pratiques](https://docs.aureusprime.com/documentation/sms/bonnes-pratiques). ## Exemple ```bash curl -X POST https://api.aureusprime.com/v1/sms/messages \ -H "Authorization: Bearer adk_sms_VOTRE_CLE" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: commande-4821" \ -d '{"to": "677000222", "text": "Commande no 4821 confirmée. Livraison demain.", "sensitive": false}' ``` ```js const response = await fetch("https://api.aureusprime.com/v1/sms/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.AUREUS_SMS_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "commande-4821", }, body: JSON.stringify({ to: "677000222", text: "Commande no 4821 confirmée." }), }); const message = await response.json(); ``` ## Réponse ```json { "id": "5b0f2c1e-8a4d-4f7e-9c3a-1d2b3c4d5e6f", "status": "QUEUED", "to": "+237*******22", "operator": "MTN", "senderId": "Aureus Desk", "errorCode": null, "scheduledAt": null, "createdAt": "2026-11-01T10:00:00.000Z", "sentAt": null, "deliveredAt": null, "likelyUndelivered": false } ``` `likelyUndelivered: true` : le numéro appartient à un opérateur que nous ne desservons pas aujourd'hui (Camtel, Nextell). Le SMS est tenté ; s'il est refusé, le crédit est rendu. ## Refus avant la file (aucun débit) | Code | Cas | |---|---| | `422 PHONE_INVALID` | Numéro mal formé | | `422 PHONE_NOT_COVERED` | Numéro hors Cameroun ou fixe | | `422 TEXT_INVALID` / `TEXT_TOO_LONG` | Texte vide, avec caractères de contrôle, ou trop long pour un SMS (160 en GSM, 70 en Unicode) | | `422 SENDER_INVALID` / `SENDER_NOT_APPROVED` / `SENDER_NOT_ALLOWED` | Expéditeur hors format, pas encore validé, ou réservé aux organisations | | `422 SCHEDULE_INVALID` | `scheduledAt` invalide | | `402 INSUFFICIENT_CREDITS` | Plus de crédits | | `403 VERIFICATION_REQUIRED` | Identité ou entreprise pas encore vérifiée | --- # Planifier un SMS Ajoutez `scheduledAt` à l'envoi pour choisir la date et l'heure de départ, **jusqu'à 30 jours à l'avance**. ```bash curl -X POST https://api.aureusprime.com/v1/sms/messages \ -H "Authorization: Bearer adk_sms_VOTRE_CLE" \ -H "Content-Type: application/json" \ -d '{"to": "699123456", "text": "Rappel : votre rendez-vous est demain à 10 h.", "scheduledAt": "2026-11-02T08:00:00+01:00"}' ``` ## Règles - **Format :** date ISO 8601 **avec fuseau** : `2026-11-02T08:00:00+01:00` (heure du Cameroun) ou `2026-11-02T07:00:00Z`. Sans fuseau : refusé. - **Dans le futur**, et **30 jours au plus** après l'appel. Sinon : `422 SCHEDULE_INVALID`. - **Crédit réservé dès la planification.** - Le SMS reste au statut `QUEUED` jusqu'à sa date, puis part comme les autres. La réponse et `GET /sms/messages/:id` renvoient `scheduledAt`. ## Annuler un SMS planifié ```http DELETE https://api.aureusprime.com/v1/sms/messages/:id ``` Tant que le SMS n'est pas parti, il passe à `CANCELLED` et **le crédit vous est rendu**. Réponse `200` avec l'état du message. | Code | Cas | |---|---| | `409 NOT_CANCELLABLE` | Le SMS n'était pas planifié, ou il est déjà parti | | `404 NOT_FOUND` | Le message n'appartient pas à votre compte | ## Conseil Pour un code à usage unique, n'utilisez pas la planification : envoyez-le tout de suite avec `"sensitive": true`. --- # Suivre un SMS ```http GET https://api.aureusprime.com/v1/sms/messages/:id ``` Renvoie l'état d'un message de votre compte, sous la même forme que la réponse d'envoi (sans `likelyUndelivered`). Le texte n'est jamais renvoyé et le numéro est masqué. ## Statuts | `status` | Sens | |---|---| | `QUEUED` | En file, crédit réservé. Un SMS planifié y reste jusqu'à sa date | | `SENDING` | En cours d'envoi | | `SENT` | Accepté par l'opérateur ; accusé de réception attendu (suivi pendant 72 h) | | `DELIVERED` | Reçu par le téléphone | | `FAILED` | Échec ; `errorCode` en donne la raison. Crédit rendu si le SMS n'a pas été envoyé | | `CANCELLED` | SMS planifié annulé par vous (crédit rendu), ou annulé par l'opérateur | `DELIVERED`, `FAILED` et `CANCELLED` sont définitifs. ## Rythme conseillé Interrogez peu après l'envoi, puis de plus en plus rarement : quelques secondes, une minute, quelques minutes. Un SMS resté `SENT` sans accusé de réception après 72 h n'est plus suivi. --- # Solde et tarifs ## Solde ```http GET https://api.aureusprime.com/v1/sms/balance ``` ```json { "balance": 120, "low": false } ``` `low` vaut `true` sous 10 % de votre dernier achat ou sous 50 crédits. Les crédits n'expirent pas. ## Grille de prix ```http GET https://api.aureusprime.com/v1/sms/price-tiers ``` ```json [ { "minQuantity": 100, "unitPriceXaf": 25 }, { "minQuantity": 501, "unitPriceXaf": 24 }, { "minQuantity": 1001, "unitPriceXaf": 23 }, { "minQuantity": 5001, "unitPriceXaf": 22 }, { "minQuantity": 10001, "unitPriceXaf": 21 }, { "minQuantity": 50001, "unitPriceXaf": 20 } ] ``` Prix dégressif en FCFA par SMS, nets (sans TVA) : **tout l'achat** est facturé au prix du palier atteint. La grille en vigueur est celle que renvoie cette route. ## Recharger Vous rechargez **un montant en FCFA, à partir de 10 000** : la plus petite recharge donne déjà 400 SMS, dans le premier palier (100 à 500 SMS). Vous recevez le nombre de SMS du palier le plus avantageux que ce montant atteint, arrondi au SMS inférieur. Avec la grille de départ : | Recharge | Prix par SMS | SMS reçus | |---|---|---| | 10 000 FCFA | 25 | 400 | | 20 000 FCFA | 24 | 833 | | 50 000 FCFA | 23 | 2 173 | | 100 000 FCFA | 23 | 4 347 | | 200 000 FCFA | 22 | 9 090 | Au-delà de 100 000 SMS : sur devis. Pendant le pilote, la recharge se fait sur demande depuis l'espace Compte ; le paiement en ligne par Mobile Money arrive avec Aureus Gate. --- # Expéditeurs L'expéditeur est le nom affiché sur le téléphone de vos clients. - **Expéditeur commun :** utilisé par défaut, disponible tout de suite pour tous les comptes. - **Expéditeur propre :** réservé aux **organisations**. Un nom de 2 à 11 lettres, chiffres ou espaces simples, utilisable après validation par l'opérateur (quelques jours). ## Lister vos expéditeurs ```http GET https://api.aureusprime.com/v1/sms/senders ``` ```json [{ "id": "…", "name": "BOUTIQUEX", "status": "APPROVED", "createdAt": "2026-11-01T10:00:00.000Z" }] ``` `status` : `PENDING` (en validation), `APPROVED` (utilisable) ou `REJECTED`. ## Demander un expéditeur ```http POST https://api.aureusprime.com/v1/sms/senders ``` ```json { "name": "BOUTIQUEX" } ``` Réponse `201` au statut `PENDING`. Ensuite, envoyez avec `"senderId": "BOUTIQUEX"` une fois le nom validé ; avant, l'envoi est refusé (`422 SENDER_NOT_APPROVED`). | Code | Cas | |---|---| | `422 SENDER_INVALID` | Nom hors format | | `422 SENDER_NOT_ALLOWED` | Compte de particulier | | `409 CONFLICT` | Nom déjà demandé | --- # Bonnes pratiques ## Ne jamais débiter deux fois Après une coupure réseau, vous ne savez pas si votre envoi est arrivé. Renvoyez-le avec la **même** `Idempotency-Key` (par exemple l'identifiant de la commande) : s'il était arrivé, vous recevez le même message, sans nouveau débit. ## Codes à usage unique Envoyez-les avec `"sensitive": true` : leur texte est effacé dès l'envoi et n'est jamais conservé. Ne les planifiez pas. ## Nouveaux essais - `5xx` ou délai dépassé : réessayez avec la même `Idempotency-Key`, en espaçant les essais (1 s, 5 s, 30 s). - `4xx` : ne réessayez pas tel quel ; corrigez la requête (voir [Erreurs](https://docs.aureusprime.com/reference/sms/erreurs)). ## Sécurité - Clé d'API côté serveur uniquement ; jamais dans une application mobile ni dans une page web. - Deux clés actives au plus : utilisez la seconde pour changer de clé sans coupure. - Les numéros sont masqués dans toutes les réponses : stockez vous-même la correspondance si vous en avez besoin. ## SMS autorisés L'API sert aux SMS **transactionnels** : codes, confirmations, rappels, alertes liés à un service que le destinataire utilise. La prospection commerciale et les messages non sollicités sont interdits par les [conditions d'utilisation](https://desk.aureusprime.com/fr/cgu). ## Texte 160 caractères en alphabet GSM, 70 seulement dès qu'un caractère en sort (ê, ô, ç, °, ’, emoji). Préférez un texte court et clair, sans ces caractères quand c'est possible, avec le nom de votre entreprise s'il n'apparaît pas dans l'expéditeur. --- # Référence de l'API SMS **Base :** `https://api.aureusprime.com/v1` · **Authentification :** `Authorization: Bearer adk_sms_VOTRE_CLE` · **Format :** JSON, UTF-8. | Méthode | Route | Rôle | Détail | |---|---|---|---| | `POST` | `/sms/messages` | Envoyer un SMS, tout de suite ou à une date planifiée | [Envoyer](https://docs.aureusprime.com/documentation/sms/envoyer), [Planifier](https://docs.aureusprime.com/documentation/sms/planifier) | | `GET` | `/sms/messages/:id` | État d'un message | [Suivre](https://docs.aureusprime.com/documentation/sms/suivre) | | `DELETE` | `/sms/messages/:id` | Annuler un SMS planifié pas encore parti (crédit rendu) | [Planifier](https://docs.aureusprime.com/documentation/sms/planifier) | | `GET` | `/sms/balance` | Solde de crédits et alerte de solde bas | [Solde et recharges](https://docs.aureusprime.com/documentation/sms/solde-tarifs) | | `GET` | `/sms/price-tiers` | Grille de prix dégressive | [Solde et recharges](https://docs.aureusprime.com/documentation/sms/solde-tarifs) | | `GET` | `/sms/senders` | Vos expéditeurs et leur statut | [Expéditeurs](https://docs.aureusprime.com/documentation/sms/expediteurs) | | `POST` | `/sms/senders` | Demander un expéditeur propre (organisations) | [Expéditeurs](https://docs.aureusprime.com/documentation/sms/expediteurs) | ## Objet message | Champ | Type | Description | |---|---|---| | `id` | string (UUID) | Identifiant du message | | `status` | string | `QUEUED`, `SENDING`, `SENT`, `DELIVERED`, `FAILED` ou `CANCELLED` | | `to` | string | Numéro masqué (`+237*******56`) | | `operator` | string ou null | `MTN`, `ORANGE`… | | `senderId` | string | Expéditeur utilisé | | `errorCode` | string ou null | Raison d'un échec | | `scheduledAt` | string ou null | Date d'envoi planifiée (ISO 8601) | | `createdAt`, `sentAt`, `deliveredAt` | string ou null | Dates (ISO 8601, UTC) | | `likelyUndelivered` | boolean | À l'envoi seulement : opérateur non desservi aujourd'hui | | `replayed` | boolean | Présent quand une `Idempotency-Key` rejoue un message existant | Le texte d'un message n'est jamais renvoyé. --- # Authentification Chaque appel porte votre clé d'API dans l'en-tête `Authorization` : ```http Authorization: Bearer adk_sms_VOTRE_CLE ``` Sans clé, ou avec une clé révoquée : `401 AUTH_REQUIRED`. Compte suspendu : `403 ACCOUNT_SUSPENDED`. ## Vos clés - Une clé est rattachée à **votre compte SMS** : elle ne voit et ne dépense que vos crédits. - Elle est affichée **une seule fois**, à sa création. Aureus Desk n'en garde qu'une empreinte : impossible de la retrouver ensuite. - Vous pouvez avoir **2 clés actives au plus**. Une troisième création est refusée (`409 API_KEY_LIMIT`). ## Changer de clé sans coupure 1. Créez une deuxième clé. 2. Déployez-la sur vos serveurs. 3. Révoquez l'ancienne dans l'espace Compte. ## Bonnes règles - Gardez la clé **côté serveur** : jamais dans une application mobile, une page web ou un dépôt de code. - Une clé exposée doit être révoquée tout de suite : les envois faits avec elle vous sont imputés. --- # Erreurs Toutes les erreurs ont la même forme : ```json { "error": { "code": "TEXT_TOO_LONG", "message": "Le SMS dépasse la longueur d'un SMS.", "details": { "encoding": "UCS-2", "length": 74, "max": 70 } } } ``` Fiez-vous à `code`, qui est stable ; `message` est un texte lisible qui peut évoluer. `details` est facultatif. | HTTP | `code` | Cas | |---|---|---| | 400 | `VALIDATION_FAILED` | Requête invalide (champ de mauvais type, en-tête mal formé) | | 401 | `AUTH_REQUIRED` | Clé d'API absente, invalide ou révoquée | | 402 | `INSUFFICIENT_CREDITS` | Plus de crédits | | 403 | `ACCOUNT_SUSPENDED` | Compte suspendu | | 403 | `VERIFICATION_REQUIRED` | Identité ou entreprise à vérifier avant d'envoyer | | 404 | `NOT_FOUND` | Ressource absente ou hors de votre compte | | 409 | `IDEMPOTENCY_CONFLICT` | Clé d'idempotence déjà utilisée pour un autre message | | 409 | `NOT_CANCELLABLE` | Annulation d'un SMS non planifié ou déjà parti | | 409 | `CONFLICT` | Expéditeur déjà demandé | | 409 | `API_KEY_LIMIT` | 2 clés d'API actives au plus | | 422 | `PHONE_INVALID` | Numéro mal formé | | 422 | `PHONE_NOT_COVERED` | Numéro hors Cameroun ou fixe | | 422 | `TEXT_INVALID` | Texte vide ou invalide | | 422 | `TEXT_TOO_LONG` | Trop long pour un SMS : 160 en alphabet GSM, 70 en Unicode ; `details` donne `encoding`, `length`, `max` | | 422 | `SENDER_INVALID` | Expéditeur hors format | | 422 | `SENDER_NOT_APPROVED` | Expéditeur pas encore validé | | 422 | `SENDER_NOT_ALLOWED` | Expéditeur propre demandé par un particulier | | 422 | `SCHEDULE_INVALID` | Date de planification invalide | | 429 | `RATE_LIMITED` | Plus de 10 requêtes par seconde pour une même clé (réserve de 20) : attendre le nombre de secondes de l'en-tête `Retry-After`, puis réessayer avec la même `Idempotency-Key` | Un refus en `4xx` ne débite jamais de crédit. --- # Règles pour assistants IA (AGENTS.md) Copiez le texte ci-dessous dans un fichier **`AGENTS.md`** à la racine de votre projet (ou dans `CLAUDE.md`, ou dans les règles de votre éditeur). Votre assistant de code saura alors appeler l'API SMS d'Aureus Desk sans inventer de route ni de champ, et sans exposer votre clé. ~~~markdown # API SMS d'Aureus Desk — règles pour l'assistant de code Ce projet envoie des SMS au Cameroun avec l'API SMS d'Aureus Desk. Respecte ces règles à chaque modification. ## Accès - Base : https://api.aureusprime.com/v1 - Authentification : en-tête `Authorization: Bearer `. La clé commence par `adk_sms_` et se lit dans la variable d'environnement `AUREUS_SMS_API_KEY`, côté serveur uniquement. Ne jamais l'écrire dans le code, dans un fichier suivi par git, dans une application mobile ni dans une page web. - JSON en entrée et en sortie (UTF-8). ## Routes (aucune autre n'existe) - `POST /sms/messages` : corps `{ "to", "text", "senderId"?, "sensitive"?, "scheduledAt"? }` → `202`. En-tête `Idempotency-Key` à toujours envoyer. - `GET /sms/messages/{id}` : état d'un message. - `DELETE /sms/messages/{id}` : annule un SMS planifié pas encore parti (crédit rendu). - `GET /sms/balance` → `{ "balance", "low" }`. - `GET /sms/price-tiers` → `[{ "minQuantity", "unitPriceXaf" }]`. - `GET /sms/senders` ; `POST /sms/senders` avec `{ "name" }` (organisations). ## Règles - `to` : mobile du Cameroun (MTN, Orange), par exemple `699123456` ou `+237699123456`. - `text` : 1 SMS = 160 caractères en alphabet GSM (`€ [ ] { } ^ ~ | \` comptent 2), mais 70 dès qu'un caractère sort de l'alphabet GSM (ê, ô, î, ç, « », °, ’, emoji ; un emoji compte 2). Ne jamais tronquer : raccourcir ou refuser. - `Idempotency-Key` : stable et dérivée de l'objet métier (`commande-4821`, `otp--`), réutilisée telle quelle pour tout nouvel essai. - Code à usage unique : `"sensitive": true`, envoyé tout de suite, jamais planifié. - `scheduledAt` : ISO 8601 avec fuseau (`2026-11-02T08:00:00+01:00`), dans le futur, 30 jours au plus. - Erreurs : lire `error.code` (stable), jamais `error.message`. Ne pas réessayer un `4xx`, sauf `429` après `Retry-After`. Réessayer un `5xx` ou un délai dépassé avec la même `Idempotency-Key` (1 s, puis 5 s, puis 30 s). - Statuts : `QUEUED`, `SENDING`, `SENT`, `DELIVERED`, `FAILED`, `CANCELLED`. Définitifs : `DELIVERED`, `FAILED`, `CANCELLED`. - Les numéros reviennent masqués : garder côté projet le lien entre l'`id` du message et son destinataire. - SMS transactionnels uniquement (codes, confirmations, rappels, alertes) : jamais de prospection. ## Codes d'erreur - 400 `VALIDATION_FAILED` · 401 `AUTH_REQUIRED` · 402 `INSUFFICIENT_CREDITS` · 403 `ACCOUNT_SUSPENDED`, `VERIFICATION_REQUIRED` - 404 `NOT_FOUND` · 409 `IDEMPOTENCY_CONFLICT`, `NOT_CANCELLABLE`, `CONFLICT` - 422 `PHONE_INVALID`, `PHONE_NOT_COVERED`, `TEXT_INVALID`, `TEXT_TOO_LONG`, `SENDER_INVALID`, `SENDER_NOT_APPROVED`, `SENDER_NOT_ALLOWED`, `SCHEDULE_INVALID` - 429 `RATE_LIMITED` : 10 requêtes/s par clé (réserve 20) ; attendre `Retry-After` secondes, même `Idempotency-Key` Documentation complète en texte brut : https://docs.aureusprime.com/llms-full.txt ~~~ ## Pour aller plus loin - Un **skill** prêt à installer, avec une fonction d'envoi déjà écrite : [Skill Aureus SMS](https://docs.aureusprime.com/integration-ia/sms/skill). - Toute la documentation en une page de texte brut : [llms.txt et llms-full.txt](https://docs.aureusprime.com/integration-ia/sms/llms). --- # Skill Aureus SMS Un **skill** donne à votre assistant de code une méthode complète pour une tâche précise. Créez le fichier ci-dessous dans votre projet : - **Claude Code :** `.claude/skills/aureus-sms/SKILL.md` - **Codex :** `.codex/skills/aureus-sms/SKILL.md` (ou l'emplacement de skills de votre outil) ~~~markdown --- name: aureus-sms description: Envoyer, planifier, annuler et suivre des SMS au Cameroun avec l'API SMS d'Aureus Desk. À utiliser dès que le code doit envoyer un code de connexion, une confirmation, un rappel ou une alerte par SMS. --- # Envoyer des SMS avec Aureus Desk ## Avant d'écrire du code 1. Vérifier que la variable d'environnement `AUREUS_SMS_API_KEY` existe côté serveur (jamais côté client). 2. Réutiliser le module `aureusSms` du projet s'il existe ; sinon, le créer avec le code ci-dessous. ## Module à utiliser (TypeScript, Node 18 ou plus) ```ts const BASE = "https://api.aureusprime.com/v1"; export type SmsStatus = "QUEUED" | "SENDING" | "SENT" | "DELIVERED" | "FAILED" | "CANCELLED"; export interface SmsMessage { id: string; status: SmsStatus; to: string; operator: string | null; senderId: string; errorCode: string | null; scheduledAt: string | null; createdAt: string; sentAt: string | null; deliveredAt: string | null } export class AureusSmsError extends Error { constructor(readonly status: number, readonly code: string, message: string) { super(message); } } async function call(method: string, path: string, body?: unknown, idempotencyKey?: string): Promise { const response = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${process.env.AUREUS_SMS_API_KEY}`, "Content-Type": "application/json", ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}), }, body: body === undefined ? undefined : JSON.stringify(body), }); const json = await response.json().catch(() => null); if (!response.ok) throw new AureusSmsError(response.status, json?.error?.code ?? "UNKNOWN", json?.error?.message ?? response.statusText); return json as T; } /** Envoie un SMS. `idempotencyKey` stable (ex. `commande-4821`) : la réutiliser pour tout nouvel essai. */ export function sendSms(input: { to: string; text: string; idempotencyKey: string; sensitive?: boolean; scheduledAt?: string; senderId?: string }) { const { idempotencyKey, ...body } = input; return call("POST", "/sms/messages", body, idempotencyKey); } export const getSms = (id: string) => call("GET", `/sms/messages/${id}`); export const cancelSms = (id: string) => call("DELETE", `/sms/messages/${id}`); export const getBalance = () => call<{ balance: number; low: boolean }>("GET", "/sms/balance"); ``` ## Règles - 1 SMS = 160 caractères en alphabet GSM, 70 dès qu'un caractère en sort (ê, ô, ç, °, ’, emoji) : raccourcir ou refuser, jamais tronquer. - Code à usage unique : `sensitive: true`, jamais `scheduledAt`. - `scheduledAt` : ISO 8601 avec fuseau (`+01:00`), futur, 30 jours au plus ; `cancelSms` pour annuler. - Gérer les erreurs par `AureusSmsError.code`. Ne pas réessayer un `4xx` ; réessayer un `5xx` avec la même clé d'idempotence. - Stocker l'`id` renvoyé avec le destinataire : les numéros reviennent masqués. - SMS transactionnels uniquement ; jamais de prospection. Référence complète : https://docs.aureusprime.com/llms-full.txt ~~~ --- # llms.txt et llms-full.txt Deux adresses servent la documentation en **texte brut**, faciles à lire pour un agent ou un assistant de code : | Adresse | Contenu | |---|---| | https://docs.aureusprime.com/llms.txt | Index : une ligne par page, avec son résumé | | https://docs.aureusprime.com/llms-full.txt | Toute la documentation publique de l'API SMS, en une seule page | Elles sont générées à partir des mêmes textes que ce site : elles sont toujours à jour. ## Les donner à votre assistant Dans une conversation, collez l'adresse de `llms-full.txt` et demandez à votre assistant de la lire avant d'écrire du code. Pour la garder dans votre projet : ```bash curl -fsSL https://docs.aureusprime.com/llms-full.txt -o docs/aureus-sms.md ``` Pour des règles permanentes, préférez le texte de la page [Règles pour assistants IA](https://docs.aureusprime.com/integration-ia/sms/assistants-ia).