Votre premier SMS

1. Préparer votre organisation

Votre organisation doit disposer d’une installation SMS active et de crédits disponibles. Créez une clé organisationnelle avec sms.send et delivery.read dans BEFIANA Cloud.

Vous préparez votre accès pour la première fois ? Suivez les premiers pas, puis la création d’une clé API. Le guide Authentification explique le format Bearer et les permissions à sélectionner.

Les commandes suivantes sont destinées à un terminal Bash. Remplacez le numéro de démonstration par un destinataire autorisé. Leur exécution peut envoyer un SMS réel et consommer des crédits.

export BEFIANA_SMS_API_KEY='bf_sms_REPLACE_WITH_YOUR_KEY'

2. Créer le message

Remplacez la valeur d’exemple order-2026-0001-confirmation par un identifiant propre à votre opération. Conservez-le pour toutes ses reprises, avec le même corps. Un nouvel envoi volontaire utilise une autre clé ; changer le numéro ou le texte avec une clé déjà utilisée provoque un conflit. Ne changez jamais de clé pour contourner une erreur ou un résultat incertain.

curl --include --request POST 'https://api.befiana.cloud/api/sms/v2/messages/' \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-0001-confirmation' \
  --data '{"to":"+261340000000","text":"Hello from BEFIANA."}'

--include affiche les en-têtes HTTP avec le corps. Un envoi immédiat accepté renvoie 201 et une adresse Location relative à https://api.befiana.cloud. Exemple de réponse, avec identifiant et dates illustratifs :

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/sms/v2/messages/12f27a77-9666-472d-a34f-90e89371dcd5/

{
  "id": "12f27a77-9666-472d-a34f-90e89371dcd5",
  "to": "+261340000000",
  "sender_name": "BEFIANA",
  "segments": 1,
  "status": "accepted",
  "send_at": null,
  "delivery_time": null
}

Conservez id et votre clé d’idempotence. accepted confirme l’acceptation par le fournisseur, pas la livraison au téléphone. segments indique le nombre de segments du message ; send_at vaut null pour un envoi immédiat.

L’exemple suppose que le nom résolu est BEFIANA. Sans sender_name, le service peut utiliser le nom par défaut de votre organisation : ne testez pas votre intégration en exigeant cette valeur d’exemple.

Si la connexion est interrompue, reprenez le même corps avec la même clé d’idempotence. Une reprise rejoue la réponse de création initiale ; elle ne remplace pas la consultation du statut courant. Après effacement des données du message, un 410 personal_data_erased arrête les reprises : conservez la clé sans nouvel envoi. Voir l’idempotence.

3. Consulter le statut courant

Remplacez MESSAGE_ID par l’identifiant retourné.

export MESSAGE_ID='REPLACE_WITH_RETURNED_UUID'
curl "https://api.befiana.cloud/api/sms/v2/messages/$MESSAGE_ID/" \
  --header "Authorization: Bearer $BEFIANA_SMS_API_KEY"

La réponse HTTP 200 utilise les mêmes champs. Voici un exemple après réception d’un accusé de livraison :

{
  "id": "12f27a77-9666-472d-a34f-90e89371dcd5",
  "to": "+261340000000",
  "sender_name": "BEFIANA",
  "segments": 1,
  "status": "delivered",
  "send_at": null,
  "delivery_time": "2030-01-15T06:00:12Z"
}

Il est normal de consulter le message avant cet accusé et de recevoir encore accepted. Ne supposez aucun délai fixe. Consultez les statuts pour traiter les échecs et les résultats inconnus sans créer de doublon.

Si le premier appel n’aboutit pas

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

Réponse	Première vérification
`401 invalid_api_key`	Vérifiez la clé complète, son état actif et le préfixe `Bearer` dans Authentification.
`403`	Lisez `error.code` : vérifiez les permissions de la clé, l’activation SMS ou le nom d’expéditeur selon le code retourné.
`409`	Distinguez `insufficient_credits` (régulariser les crédits), `idempotency_in_progress` (attendre) et `idempotency_conflict` (retrouver le corps initial). Ne changez pas automatiquement de clé.
`502 provider_result_unknown`	Conservez `message_id` et consultez son statut avec le GET ci-dessus. Ne refaites pas le POST. Sans identifiant exploitable, demandez une vérification à l’assistance.

Le catalogue des erreurs SMS précise l’action pour chaque code. Si le problème persiste, préparez une demande d’assistance avec l’heure, le code et l’identifiant public, sans votre clé API.

Choisir la suite

Envoyer immédiatement avec votre propre nom d’expéditeur.
Programmer un message ou un lot.
Appliquer une recette d’intégration et gérer les reprises.
Consulter la référence API pour tous les champs et réponses.

La référence du portail reste consultative : elle ne demande aucune clé et ne lance aucune requête vers la production.