Aller au contenu
Aureus PrimeDocs

Intégration IA

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é.

# 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 <clé>`. 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-<userId>-<horodatage>`),
  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