Référence API

Référence de l'API actuelle ChinqIT Verify. Base : https://sms.chinqit.com/api/v2.

Authentification

Toutes les requêtes doivent inclure la clé API dans l'un de ces en-têtes :

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

ou

Authorization: Bearer votre-clé-api

Les clés API sont fournies par ChinqIT Verify. Contactez votre administrateur pour en obtenir une.

401 Unauthorized (clé manquante) :

{
  "success": false,
  "message": "API key is required. Please provide X-API-Key header or Authorization Bearer token."
}

403 Forbidden (clé invalide ou inactive) :

{
  "success": false,
  "message": "Invalid or inactive API key."
}

403 Forbidden (clé non liée à un compte de facturation — endpoints d'envoi uniquement) :

{
  "success": false,
  "message": "API key is not linked to a billing account"
}

403 Forbidden (sender ID expiré — endpoints d'envoi SMS uniquement) :

{
  "success": false,
  "code": "SENDER_ID_EXPIRED",
  "message": "The API key sender ID has expired. Remove it or renew the sender ID before sending SMS."
}

Lorsqu'un sender ID (header) lié à la clé expire, la gateway bloque le trafic SMS pour cette clé au lieu de retomber sur l'expéditeur par défaut. Retirez le header expiré de la clé dans le dashboard ou renouvelez-le, puis réessayez. Les envois WhatsApp ne sont pas affectés.

URL de base

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

Formats de numéro

Les règles dépendent de l'endpoint et du canal OTP.

SMS (POST /api/v2/notify, POST /api/v2/code avec channel: "sms", POST /api/v2/check avec channel: "sms")

Numéros mauritaniens uniquement. Entrées normalisées en +222XXXXXXXX :

• Canonique : +222XXXXXXXX (ex. +22238089336)
• Avec indicatif : 222XXXXXXXX
• Local : XXXXXXXX (doit commencer par 2, 3 ou 4)

OTP WhatsApp (POST /api/v2/code avec channel: "whatsapp")

Format international E.164 (ex. +12133734253).

Pays pris en charge : Mauritanie (MR) et États-Unis (US). Les autres pays renvoient 400 avec :

"WhatsApp OTP supports only Mauritania (MR) and United States (US) phone numbers."

Exemple US : +12133734253.

Utilisez le même numéro E.164 (et le même channel) pour POST /api/v2/check.

Les formats invalides renvoient 400 Bad Request.

Limites de débit

Débit global (notify, code, check, GET statut)

Par clé API : 10 requêtes par seconde. Les réponses incluent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. En cas de dépassement : 429 avec le champ retryAfter (secondes).

Les limites de débit standard ne s'appliquent pas aux requêtes bulk.

Envoi OTP (POST /api/v2/code uniquement)

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

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

En cas de dépassement : 429 avec retryAfter (secondes).

POST /api/v2/notify

Envoyer un SMS.

Requête :

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

Réponse :

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "queued": true,
  "cost": 0.10,
  "parts": 1,
  "pricePerMessage": 0.10,
  "encoding": "GSM-7",
  "length": 37
}

cost, parts, pricePerMessage, encoding et length reflètent la facturation prévue au moment de la requête (la valeur définitive est visible via GET /api/v2/notify/:messageId).

Les messages sont mis en file et traités de façon asynchrone. Utilisez messageId pour suivre la livraison.

La facturation est débitée lorsque la requête est acceptée. Une réponse 200 avec queued: true signifie que votre compte a été débité ; interrogez GET /api/v2/notify/:messageId pour le résultat de livraison (sent, providerError). En cas de 402, la requête est rejetée mais messageId est tout de même renvoyé pour interroger le statut d'échec.

Erreurs : 503 si l'envoi SMS est temporairement indisponible.

402 Payment Required — Solde insuffisant :

{
  "success": false,
  "message": "Insufficient balance",
  "messageId": "550e8400-e29b-41d4-a716-446655440000"
}

Exemple :

curl -X POST https://sms.chinqit.com/api/v2/notify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+22238089336", "message": "Bonjour"}'

POST /api/v2/code

Demander un OTP (envoyer un code de vérification par SMS ou WhatsApp).

Requête :

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

Réponse :

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 600,
  "cost": 0.10,
  "parts": 1,
  "pricePerMessage": 0.10,
  "encoding": "GSM-7",
  "length": 37
}

cost, parts, pricePerMessage, encoding et length reflètent la facturation prévue au moment de la requête (la valeur définitive est visible via GET /api/v2/notify/:messageId).

• Code à 6 chiffres, valide 10 minutes (600 secondes), 3 tentatives de vérification max.

402 Payment Required — Solde insuffisant (SMS et WhatsApp) :

{
  "success": false,
  "message": "Insufficient balance",
  "messageId": "550e8400-e29b-41d4-a716-446655440000"
}

Pour l'OTP SMS, la facturation est débitée lorsque la requête est acceptée. Une réponse 200 signifie que votre compte a été débité ; interrogez le statut pour le résultat de livraison.

Canal WhatsApp (channel: "whatsapp") :

• Votre clé API doit avoir WhatsApp activé ; sinon 403 avec "WhatsApp access is not enabled for this API key".
• Numéro E.164 valide pour MR ou US uniquement (voir Formats de numéro) ; les autres pays renvoient 400.
• 503 si l'envoi WhatsApp est temporairement indisponible.

Exemple :

curl -X POST https://sms.chinqit.com/api/v2/code \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+22238089336", "language": "en"}'

POST /api/v2/check

Vérifier un code OTP.

Requête :

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

Réponse (succès) :

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

Réponse (invalide) :

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

Exemple :

curl -X POST https://sms.chinqit.com/api/v2/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+22238089336", "otp": "123456"}'

GET /api/v2/notify/

Obtenir le statut de livraison d'un message.

Réponse :

{
  "success": true,
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "sent",
    "billed": true,
    "sent": true,
    "phoneNumber": "+22238089336",
    "type": "message",
    "channel": "sms",
    "origin": "internal_alert",
    "alertType": "low_balance",
    "smppMessageId": "abc123",
    "submittedAt": "2024-01-15T10:30:00.000Z",
    "dlrStatus": "DELIVRD",
    "dlrReceivedAt": "2024-01-15T10:30:05.000Z",
    "cost": 0.10,
    "parts": 1,
    "pricePerMessage": 0.10,
    "providerError": null,
    "createdAt": "2024-01-15T10:29:55.000Z",
    "updatedAt": "2024-01-15T10:30:05.000Z"
  }
}

Exemple d'échec de livraison :

{
  "success": true,
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "billed": false,
    "sent": false,
    "phoneNumber": "+22238089336",
    "type": "message",
    "channel": "sms",
    "providerError": {
      "code": "NO_CREDIT",
      "message": "Insufficient balance",
      "statusCode": 402
    },
    "createdAt": "2024-01-15T10:29:55.000Z",
    "updatedAt": "2024-01-15T10:29:56.000Z"
  }
}

404 si le message est introuvable ou n'appartient pas à votre clé API.

Exemple :

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://sms.chinqit.com/api/v2/notify/550e8400-e29b-41d4-a716-446655440000"

Diffusions

Envoi jusqu'à 50 000 destinataires par lot pour des messages d'une seule partie. Les messages multi-parties ou de longueur maximale réduisent la capacité — le corps de la requête est limité à 20 Mo (destinataires × (octets du message encodé + ~40 octets) ≤ 20 Mo). Voir le guide Diffusions pour :

• POST /api/v2/bulk/send (réponse 202 Accepted)
• GET /api/v2/bulk/status/:batchId

Format des erreurs

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

Codes HTTP :

Codes d'erreur fournisseur

Ces codes apparaissent dans le champ providerError.code lors de la récupération du statut via GET /api/v2/notify/:messageId.

Les échecs de facturation des envois en masse sont documentés dans le guide Diffusions.

Dépréciation

Les anciens endpoints sans version (/messages/send, /otp/send, etc.) restent disponibles mais renvoient l'en-tête Deprecation: true et un objet deprecation dans le JSON. Ne les utilisez pas pour de nouvelles intégrations. Voir la section API dépréciée.

Voir aussi

• Guide d'utilisation de l'API
• Dépannage
• Guide SMS Retriever

API v1 (dépréciée) : section legacy