Aller au contenu principal

Référence API

Documentation de référence complète pour l'API REST de la passerelle SMS Chinqit.

Authentification​

Tous les endpoints de l'API nécessitent une authentification à l'aide d'une clé API fournie par Chinqit.

En-tête d'Authentification​

Incluez votre clé API dans l'en-tête de la requête :

X-API-Key: votre-clé-api-ici

Obtenir une Clé API​

Les clés API sont fournies par Chinqit. Contactez votre administrateur de service pour obtenir votre clé API.

Réponses d'Erreur​

401 Non Autorisé - Clé API manquante :

{
  "success": false,
  "message": "API key is required"
}

403 Interdit - Clé API invalide :

{
  "success": false,
  "message": "Invalid API key"
}

URL de Base​

Toutes les requêtes API doivent être adressées à :

  • Production : https://sms.chinqit.com

Format de Numéro de Téléphone (Mauritanie)​

Tous les endpoints acceptent les numéros de téléphone mauritaniens dans les formats suivants :

  • Format canonique : +222XXXXXXXX (ex. +22238089336)
  • Avec code pays : 222XXXXXXXX (ex. 22238089336) - automatiquement normalisé en +222XXXXXXXX
  • Format local : XXXXXXXX (ex. 38089336) - automatiquement normalisé en +222XXXXXXXX

Règles :

  • Le numéro local à 8 chiffres (XXXXXXXX) doit commencer par 2, 3 ou 4
  • L'API normalise automatiquement tous les formats acceptés en +222XXXXXXXX avant de stocker ou d'envoyer
  • Les numéros de téléphone sont stockés et utilisés au format normalisé (+222XXXXXXXX) pour garantir la cohérence
  • Les formats invalides (longueur incorrecte, préfixe incorrect, contient des espaces/tirets) retourneront une erreur 400 Bad Request

Exemples :

  • ✅ +22238089336 → normalisé en +22238089336
  • ✅ 22238089336 → normalisé en +22238089336
  • ✅ 38089336 → normalisé en +22238089336
  • ❌ 12345678 → Erreur : doit commencer par 2, 3 ou 4
  • ❌ +222 27 63 56 42 → Erreur : espaces non autorisés
  • ❌ +1234567890 → Erreur : pas un numéro mauritanien valide

Opérations de Messages​

Envoyer un Message​

POST /messages/send

Envoyer un message SMS à un numéro de téléphone.

En-têtes de Requête :

X-API-Key: votre-clé-api
Content-Type: application/json

Corps de la Requête :

{
  "message": "Bonjour, ceci est un message de test",
  "phoneNumber": "+22238089336"
}

Paramètres :

  • message (obligatoire) : Contenu du message SMS
  • phoneNumber (obligatoire) : Numéro de téléphone du destinataire (format Mauritanie). Voir Format de Numéro de Téléphone ci-dessus pour plus de détails.

Réponse :

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "queued": true
}

Notes Importantes :

  • Les messages sont mis en file d'attente et traités de manière asynchrone
  • L'API retourne immédiatement après la mise en file d'attente (non bloquant)
  • Utilisez le messageId pour suivre votre message

Opérations OTP​

Envoyer un OTP​

POST /otp/send

Envoyer un code de mot de passe à usage unique (OTP) par SMS ou WhatsApp.

Corps de la Requête :

{
  "phoneNumber": "+22238089336",
  "hash": "ABC123XYZ45",
  "language": "en",
  "channel": "sms"
}

Paramètres :

  • phoneNumber (obligatoire) : Numéro de téléphone auquel envoyer l'OTP (format Mauritanie).
  • hash (optionnel) : Hash SMS Retriever de 11 caractères (canal SMS uniquement). Lorsqu'il est fourni, le hash sera ajouté au message OTP sur une nouvelle ligne. Voir Guide SMS Retriever.
  • language (optionnel) : Langue du message OTP. Options : fr (par défaut), en, ar
  • channel (optionnel) : Canal de communication. Options : sms (par défaut), whatsapp

Réponse :

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 600
}

Détails de l'OTP :

  • Code numérique à 6 chiffres
  • Valide pendant 10 minutes (600 secondes)
  • Maximum 3 tentatives de vérification
  • Peut être envoyé par SMS ou WhatsApp

Vérifier un OTP​

POST /otp/verify

Vérifier un code OTP qui a été envoyé à un numéro de téléphone.

Corps de la Requête :

{
  "phoneNumber": "+22238089336",
  "otp": "123456",
  "channel": "sms"
}

Paramètres :

  • phoneNumber (obligatoire) : Numéro de téléphone auquel l'OTP a été envoyé
  • otp (obligatoire) : Code OTP à 6 chiffres à vérifier
  • channel (optionnel) : Canal de communication utilisé. Options : sms (par défaut), whatsapp

Réponse (Succès) :

{
  "success": true,
  "message": "OTP verified successfully",
  "verified": true
}

Réponse (Invalide) :

{
  "success": false,
  "message": "Invalid OTP",
  "retriesLeft": 2
}

Réponses d'Erreur​

Tous les endpoints retournent les erreurs dans un format cohérent :

{
  "success": false,
  "message": "Description de l'erreur",
  "errors": []
}

Codes de Statut HTTP​

  • 200 OK : Requête réussie
  • 400 Bad Request : Données de requête invalides ou erreur de validation
  • 401 Unauthorized : Clé API manquante
  • 403 Forbidden : Clé API invalide
  • 404 Not Found : Ressource non trouvée
  • 429 Too Many Requests : Limite de débit dépassée
  • 500 Internal Server Error : Erreur du serveur
  • 502 Bad Gateway : Erreur du fournisseur (pour le canal WhatsApp)

Limitation de Débit​

Envoi d'OTP​

Par numéro de téléphone par clé API :

  • 3 requêtes par minute
  • 10 requêtes par heure
  • 20 requêtes par jour

Les limites de débit sont automatiquement appliquées. Si elles sont dépassées, vous recevrez un code de statut 429.

Bonnes Pratiques​

Sécurité de la Clé API​

  • Ne jamais valider les clés API dans le contrôle de version
  • Utiliser des variables d'environnement ou une gestion sécurisée des secrets
  • Faire pivoter les clés périodiquement
  • Utiliser HTTPS pour toutes les requêtes API

Gestion des Erreurs​

  • Toujours vérifier le champ success dans les réponses
  • Gérer tous les codes de statut HTTP de manière appropriée
  • Implémenter une logique de nouvelle tentative pour les erreurs transitoires (429, 500, 502)
  • Journaliser les erreurs pour le débogage

Envoi de Messages​

  • Stocker le messageId à des fins de suivi
  • Gérer les erreurs avec élégance
  • Implémenter une gestion appropriée des délais d'attente

Bonnes Pratiques OTP​

  • Toujours vérifier les OTP côté serveur
  • Ne pas exposer les codes OTP dans les journaux
  • Gérer les limites de débit avec élégance
  • Utiliser le canal approprié (SMS ou WhatsApp) en fonction des préférences de l'utilisateur

Ressources Supplémentaires​

Besoin d'aide ? Consultez le Guide de Dépannage pour les problèmes courants !