Documents API

Authentification

Envoyez la clé API de votre compte soit dans Autorisation : Porteur YOUR_API_KEY, soit dans le champ de demande de clé.Choisissez une méthode ;le champ clé fonctionne avec les panels de revendeurs courants.Conservez les clés dans les variables d'environnement côté serveur et faites-les pivoter à partir du compte.

Toutes les actions utilisent POST https://smm.africa/api/v3. Corps pris en charge : application/json, application/x-www-form-urlencoded et multipart/form-data avec des champs de texte uniquement. Les réponses sont JSON. Le champ d'action sélectionne l'opération.

curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST https://smm.africa/api/v3 \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "action=balance"

Tous les soldes, frais et montants de commande de la v3 sont retournés en USD pour des raisons de compatibilité.

Erreurs et tentatives

Vérifiez l'état HTTP et le champ d'erreur JSON. Les erreurs d'authentification utilisent HTTP 400 ; Les appelants d'API ne sont pas redirigés vers la connexion. Enregistrez les erreurs techniques en privé et montrez aux clients un message neutre.

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "request_id": "request-123",
  "retryable": false
}

Ajouter la relecture des réponses pendant 24 heures. Après expiration, la même clé peut créer une autre commande : réconcilier d'abord. REQUEST_IN_PROGRESS autorise la même demande/clé après Retry-After. IDEMPOTENCY_CONFLICT nécessite la restauration de la charge utile d'origine. ACTION_OUTCOME_UNCONFIRMED nécessite un examen du support : ne modifiez jamais les clés pour le contourner. PRICE_LIMIT_EXCEEDED signifie qu'aucun débit ou commande n'a été engagé. Enregistrez request_id (également X-Request-Id) pour obtenir de l'aide.

Réessayez une commande sans facturer deux fois

1. Créez et conservez une clé idempotency_key unique pour chaque commande logique avant d'envoyer l'ajout. Remplacez l'exemple de clé par votre propre valeur unique.
2. Attendez jusqu'à 60 secondes pour la requête du serveur. Après 20 secondes, affichez un message en attente au client pendant que la demande backend se poursuit.
3. Si aucune réponse n'arrive, réessayez exactement la même charge utile avec la même clé après un délai. Ne générez pas de nouvelle clé. Une nouvelle tentative terminée rejoue la réponse avec X-Idempotent-Replay : true.
4. Une fois que vous recevez un identifiant de commande, enregistrez-le et utilisez le statut pour suivre cette commande. Une réponse en file d’attente signifie acceptée pour exécution et non livraison terminée.

Les en-têtes Idempotency-Key et X-Idempotency-Key sont également pris en charge. Sans clé client, une commande peut toujours être soumise, mais une nouvelle tentative après un délai d'attente ne peut pas identifier en toute sécurité la tentative initiale.

Limites de débit

Les limites sont spécifiques à l'action et configurables en fonction du déploiement. Sur HTTP 429, honorez Retry-After (secondes). Sans cet en-tête, utilisez un intervalle exponentiel avec gigue, par exemple 2, 4, 8, puis 16 secondes plus un petit délai aléatoire. Nouvelles tentatives liées et signalez des échecs persistants à votre opérateur.

Mettez en cache le catalogue récupéré avec POST /api/v3 et action=services. Actualisez-le périodiquement et vérifiez les identifiants de service actuels, les tarifs et les contraintes min/max avant de commander.

Cycle de vie des commandes

Envoyez action=status avec un ID de commande par demande. En tant que politique client de départ, interrogez toutes les 30 secondes, puis augmentez l'intervalle pour les commandes de longue durée ; limites de taux d’honneur. Échelonnez les demandes sur les commandes. Les webhooks ne sont actuellement pas pris en charge.

queued → pending → processing

États actifs : continuer l'interrogation. Les commandes peuvent sauter des états intermédiaires.

completed · partial · refunded · canceled

États du terminal : arrêter l'interrogation de livraison de routine. Partielle signifie que la livraison était incomplète ; inspecter la charge et les restes. Les demandes de recharge et d’annulation sont soumises à l’éligibilité du service et de la commande.

unknown

Un Etat non reconnu ; ne le considérez pas comme un succès et ne passez pas automatiquement une commande de remplacement. Réessayez le statut avec interruption et contactez l'assistance s'il persiste.