AgoVerify

Authentification

Toutes les requêtes API (sauf /health) doivent inclure votre clé API. Vous pouvez créer et gérer vos clés depuis la page Développeur de votre tableau de bord.

X-API-Key: av_your_api_key_here

Ou utilisez l'en-tête Bearer standard :

Authorization: Bearer av_your_api_key_here

Permissions des clés API

Permission	Description
`full`	Accès lecture et écriture (par défaut). Peut créer des commandes, annuler, recharger, renvoyer et réactiver.
`read_only`	Lecture seule. Ne peut pas créer de commandes, annuler, recharger, renvoyer ni réactiver.

Les opérations d'écriture sont marquées d'un badge POST ci-dessous et requièrent une clé full.

URL de base

https://agoverify.com/api/v1

Limitation de débit

Les limites sont appliquées par clé API. Les en-têtes de réponse indiquent votre usage actuel :

En-tête	Description
`X-RateLimit-Limit`	Requêtes maximales par fenêtre
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre courante

En cas de limitation, vous recevez une réponse 429 Too Many Requests avec un champ retry_after indiquant quand réessayer.

Endpoints

Santé et compte

GET /health

Vérifie que l'API est opérationnelle. Aucune authentification requise.

GET /balance

Récupère le solde du compte et la devise.

Activations SMS

GET /sms/services

Liste tous les services de vérification SMS disponibles via l'API.

GET /sms/countries?service={code}

Liste les pays disponibles. Filtrage optionnel par code de service.

GET /sms/price?service={code}&country={code}

Récupère le tarif d'une combinaison service/pays.

POST /sms/orders

Loue un numéro de téléphone. Corps : service_code, country_code, operator (optionnel). Clé complète requise.

GET /sms/orders

Liste les commandes SMS avec pagination. Requête : status, service, country, per_page.

GET /sms/orders/active

Liste toutes les commandes SMS actives.

GET /sms/orders/{id}

Récupère les détails d'une commande SMS spécifique.

GET /sms/orders/{id}/status

Vérifie le statut de la commande et récupère le code SMS (interroge le fournisseur).

POST /sms/orders/{id}/cancel

Annule une commande active et rembourse le solde. Clé complète requise.

POST /sms/orders/{id}/resend

Demande au fournisseur de renvoyer le SMS. Clé complète requise.

POST /sms/orders/{id}/reactivate

Réactive un numéro terminé pour recevoir un nouveau SMS (débite le solde). Clé complète requise.

Backend unifié

AgoVerify utilise un backend unifié. Le système sélectionne automatiquement le meilleur fournisseur disponible pour chaque service et pays selon la priorité configurée par l'administrateur : vous ne demandez qu'un code de service et un code de pays, la plateforme gère le reste. Aucun paramètre de fournisseur ou de serveur n'est requis ni accepté.

Exemple de création de commande SMS

curl -X POST "https://agoverify.com/api/v1/sms/orders" \
  -H "X-API-Key: av_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service_code": "wa", "country_code": "0"}'

Webhooks

Les webhooks sont envoyés en requêtes POST vers vos endpoints enregistrés. Configurez-les via la page Développeur de votre tableau de bord.

Événements SMS

sms.order.created - une nouvelle commande SMS a été créée.
sms.received - un code SMS a été reçu pour une commande.
sms.order.cancelled - une commande a été annulée et remboursée.
sms.order.expired - une commande a expiré et a été remboursée.

Chaque webhook inclut un en-tête X-Webhook-Signature (HMAC-SHA256 du corps JSON avec votre secret d'endpoint) et un en-tête X-Webhook-Event avec le nom de l'événement.

Flux de travail typique

Vérification SMS

GET /sms/services - trouvez le service dont vous avez besoin (ex. wa pour WhatsApp)
GET /sms/countries?service=wa - récupérez les pays disponibles
GET /sms/price?service=wa&country=0 - vérifiez les tarifs
POST /sms/orders - créez la commande, recevez le numéro
Utilisez le numéro sur le service cible
GET /sms/orders/{id}/status - interrogez le statut pour le code SMS (ou attendez le webhook)
POST /sms/orders/{id}/cancel - annulez si vous n'en avez plus besoin (remboursement)

Gestion des erreurs

Toutes les erreurs suivent un format cohérent :

{
  "success": false,
  "message": "Human-readable error message",
  "data": {}
}

Code	Signification
`200`	Succès
`201`	Créé
`400`	Requête invalide
`401`	Non autorisé (clé API invalide ou manquante)
`402`	Paiement requis (solde insuffisant)
`403`	Interdit (clé en lecture seule tentant une écriture)
`404`	Introuvable
`422`	Erreur de validation
`429`	Limite de débit dépassée
`500`	Erreur interne du serveur
`503`	Service indisponible (erreur du fournisseur)

Documentation API AgoVerify