Référence endpoints v1

Documentation de référence complète pour l'API REST de la ChinqIT Verify.

Authentification

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

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 Verify. 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

:::caution Déprécié Tous les endpoints de cette page sont dépréciés mais restent fonctionnels. Les réponses incluent l'en-tête Deprecation: true et un objet deprecation dans le JSON. Pour l'API actuelle, consultez la Référence API. :::

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 (v1 – Déprécié)

Envoyer un Message

POST /messages/send (Déprécié – utiliser POST /api/v2/notify)

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 (v1 – Déprécié)

Envoyer un OTP

POST /otp/send (Déprécié – utiliser POST /api/v2/code)

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 (Déprécié – utiliser POST /api/v2/check)

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
}

Opérations de statut (v1 – Déprécié)

Obtenir le statut d'un message

GET /message/:messageId/status (Déprécié – utiliser GET /api/v2/notify/

)

Récupère le statut de livraison d'un message appartenant à votre clé API.

Réponse : Même objet data que GET /api/v2/notify/

Mettre à jour le statut d'un message

POST /update-message-status (Déprécié – pas de remplacement v2)

:::warning Ne pas utiliser pour de nouvelles intégrations Il n'existe pas d'équivalent v2. Le statut de livraison est mis à jour automatiquement par ChinqIT Verify. Cet endpoint est conservé uniquement pour les clients existants. :::

Corps de la requête :

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

Réponse :

{
  "success": true,
  "message": "Message status updated successfully",
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "sent": true,
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Format de réponse de dépréciation

Tous les endpoints legacy renvoient :

En-tête : Deprecation: true
Champ JSON : deprecation avec message et useInstead

Exemple (POST /messages/send) :

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "queued": true,
  "deprecation": {
    "message": "This endpoint is deprecated. Use POST /api/v2/notify instead.",
    "useInstead": "POST /api/v2/notify"
  }
}

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

En cas de dépassement, l'API renvoie le code HTTP 429 avec un champ retryAfter le cas échéant.

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

Référence API – API actuelle (à utiliser pour les nouvelles intégrations)
Guide d'Utilisation de l'API – exemples de code (v1 déprécié)
Guide de Dépannage – problèmes courants et solutions

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

Référence endpoints v1

On this page