SIM Swap

Le SIM Swap (changement de carte) fait référence au processus d'association du numéro de téléphone d'un utilisateur à une nouvelle carte SIM. Cela se produit généralement dans les scénarios suivants : déclaration de perte et remplacement de carte, mise à niveau de la carte SIM, portabilité du numéro, activation de services multi-SIM, ou lorsqu'un nouvel utilisateur hérite d'un numéro précédemment utilisé par quelqu'un d'autre.

Les attaquants peuvent utiliser le SIM Swap pour pirater le numéro de téléphone d'une autre personne, intercepter les codes de vérification par SMS, puis réinitialiser les mots de passe et prendre le contrôle des comptes. L'API SIM Swap permet de détecter en temps réel si un numéro de téléphone spécifié a fait l'objet d'un changement de carte SIM, aidant ainsi les entreprises à identifier les risques potentiels de piratage de SIM lors d'étapes critiques telles que la vérification OTP par SMS, et à réduire la probabilité de prise de contrôle de compte.

Remarque : Actuellement, la vérification du SIM Swap n'est prise en charge que pour les numéros des pays/régions suivants : Brésil, Indonésie.

Cette API fournit deux interfaces indépendantes :

• Retrieve Date : interroger l'heure du dernier SIM Swap survenu pour un numéro de téléphone spécifié
• Check : détecter si un SIM Swap s'est produit pour un numéro de téléphone spécifié au cours des N dernières heures

Vérification d'appel

Ces deux interfaces utilisent la méthode d'authentification HTTP Basic Auth, en ajoutant Authorization dans l'en-tête HTTP :

              
              Authorization: Basic ${base64_auth_string}

            

L'algorithme de génération de ${base64_auth_string} est : base64(dev_key:dev_secret).

Pour plus de détails, veuillez vous référer à Vérification d'appel pour savoir comment effectuer l'authentification de l'API.

Retrieve Date

Interroger l'heure du dernier SIM Swap survenu pour un numéro de téléphone spécifié.

Adresse d'appel

POST https://otp.api.engagelab.cc/v1/sim-swap/retrieve-date

Exemple de requête

Un objet de requête est exprimé au format JSON, l'en-tête de la requête doit donc inclure Content-Type: application/json.

En-tête de requête

              
              POST /v1/sim-swap/retrieve-date HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

            

Corps de requête

              
              {
  "phone_number": "+381692223535"
}

            

Paramètres de requête

Paramètres de retour

Retour de succès

Exemple de retour de succès :

              
              {
  "request_id": "2055136570436075520",
  "latest_sim_change": "2026-05-01T15:00:00Z"
}

            

Retour d'échec

Le code d'état HTTP est 4xx ou 5xx, et le corps de la réponse contient les champs suivants :

Exemples courants de retour d'échec :

Exemple d'erreur de paramètre :

              
              {
  "code": 3002,
  "message": "invalid phone_number"
}

            

Exemple de solde insuffisant :

              
              {
  "code": 3005,
  "message": "balance not enough"
}

            

Exemple de numéro hors de la zone de couverture du service :

              
              {
  "code": 5101,
  "message": "phone number is not in sim swap service coverage"
}

            

Exemple d'échec général :

              
              {
  "code": 5100,
  "message": "failed to retrieve sim swap date"
}

            

Check

Détecter si un SIM Swap s'est produit pour un numéro de téléphone spécifié au cours des N dernières heures.

Adresse d'appel

POST https://otp.api.engagelab.cc/v1/sim-swap/check

Exemple de requête

Un objet de requête est exprimé au format JSON, et l'en-tête de la requête doit également inclure Content-Type: application/json.

En-tête de requête

              
              POST /v1/sim-swap/check HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

            

Corps de requête

              
              {
  "phone_number": "+381692223535",
  "max_age": 400
}

            

Paramètres de requête

Paramètres de retour

Retour de succès

Exemple de retour de succès :

              
              {
  "request_id": "2055136570293469184",
  "swapped": true
}

            

Retour d'échec

La structure est identique à celle de l'interface Retrieve Date. Exemple spécifique de retour d'échec :

Erreur de paramètre (max_age hors limites) :

              
              {
  "code": 3002,
  "message": "max_age must be between 1 and 2400"
}

            

Codes d'erreur