ezyyen

Documentation de l'API

Envoyez des SMS et des codes OTP depuis votre application avec une simple requête HTTP. URL de base : https://ezyyen.com/api

1. Démarrage rapide

  1. Créez un compte et confirmez votre adresse email.
  2. Rechargez votre solde depuis l'espace client : chaque envoi est débité selon la grille tarifaire du pays de destination.
  3. Dans l'espace client, ouvrez API développeur et créez une clé. Elle n'est affichée qu'une seule fois : conservez-la côté serveur, jamais dans une application mobile ou un site web public.
  4. Appelez l'endpoint d'envoi ci-dessous depuis votre serveur.

2. Authentification

Chaque requête porte votre clé dans l'en-tête Authorization. Envoyez aussi Accept: application/json pour recevoir les erreurs au format JSON.

Authorization: Bearer VOTRE_CLE_API
Accept: application/json
Content-Type: application/json

Une clé API ne donne accès qu'à l'API d'envoi : elle ne permet ni de consulter l'historique financier, ni de recharger, ni de créer d'autres clés. Vous pouvez la révoquer à tout moment depuis l'espace client ; un changement de mot de passe révoque aussi toutes vos clés.

3. Envoyer un SMS

POST https://ezyyen.com/api/v1/sms/send

ChampTypeDescription
tochaîneUn numéro au format international, par exemple +2290197000000. Requis si recipients est absent.
recipientstableauPlusieurs numéros (jusqu'à 10 000 par requête). Les numéros invalides ou vers un pays non desservi sont ignorés.
messagechaînerequisTexte du SMS, 1 600 caractères au maximum. Les messages longs sont envoyés en plusieurs segments, chacun facturé.
sender_idchaîneExpéditeur affiché (11 caractères maximum). Doit être un Sender ID approuvé pour votre compte ; par défaut EZYYEN.
campaign_namechaîneNom de l'envoi dans votre historique (128 caractères maximum).
curl -X POST https://ezyyen.com/api/v1/sms/send \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2290197000000",
    "message": "Votre code de vérification est 482913.",
    "sender_id": "EZYYEN"
  }'

4. Réponse

Code 201 lorsque l'envoi est enregistré et le montant débité de votre solde :

{
  "success": true,
  "campaign_id": "9f1c…",
  "sender_id": "EZYYEN",
  "status": "processing",
  "total_recipients": 1,
  "total_segments": 1,
  "cost_xof": 500,
  "wallet_balance_xof": 3000,
  "messages": [
    {
      "id": "9f1c…",
      "to": "2290197000000",
      "status": "submitted",
      "provider_message_id": "…",
      "cost_xof": 500
    }
  ]
}

« submitted » signifie que l'opérateur a accepté le message, pas qu'il est livré. Le statut final (delivered ou failed) arrive ensuite par l'accusé de réception de l'opérateur et s'affiche dans l'historique de l'espace client. L'API ne propose pas encore de consultation des statuts ni de webhook vers votre application.

5. Erreurs

CodeSignification
401Clé absente, invalide ou révoquée.
403Adresse email non confirmée, ou clé utilisée en dehors de l'API d'envoi.
422Requête refusée : champ manquant, solde insuffisant, expéditeur non autorisé, aucun numéro valide, compte suspendu. Le motif est dans « error » ou « errors ».
429Trop de requêtes : au plus 120 par minute pour votre compte utilisateur. Attendez avant de réessayer.
500Erreur de notre côté : l'envoi n'a pas été enregistré. Réessayez plus tard ou contactez le support.
{
  "success": false,
  "error": "Solde insuffisant pour réserver ce montant. Disponible: 0 XOF."
}

Avant de renvoyer une requête qui a expiré côté réseau, vérifiez dans votre historique qu'elle n'a pas déjà été enregistrée, pour éviter un double envoi.

6. Bonnes pratiques et règles d'envoi

  • N'envoyez qu'à des personnes qui ont accepté de recevoir vos messages, et respectez les demandes d'arrêt.
  • Les caractères spéciaux et emojis réduisent la longueur d'un segment (70 caractères au lieu de 160) : vérifiez le coût estimé dans l'espace client avant un gros envoi.
  • Un Sender ID personnalisé dépend de l'approbation d'Infobip et des opérateurs de chaque pays ; tant qu'il n'est pas approuvé, utilisez l'expéditeur par défaut.
  • Les envois sont soumis aux conditions d'utilisation. Consultez les tarifs par pays.