SIM Swap

SIM Swap (cambio de tarjeta SIM) se refiere al proceso de vincular el número de teléfono de un usuario a una nueva tarjeta SIM. Esto suele ocurrir en los siguientes escenarios: denuncia de pérdida y sustitución de tarjeta, actualización de la tarjeta SIM, portabilidad numérica, activación de servicios multi-SIM o cuando un nuevo usuario hereda un número utilizado anteriormente por otra persona.

Los atacantes pueden utilizar el SIM Swap para secuestrar el número de teléfono de otra persona, interceptar códigos de verificación por SMS y, posteriormente, restablecer contraseñas y tomar el control de las cuentas. La API de SIM Swap puede detectar en tiempo real si un número de teléfono especificado ha sufrido un cambio de tarjeta SIM, ayudando a las empresas a identificar posibles riesgos de secuestro de SIM en procesos críticos como la verificación OTP por SMS y reduciendo la probabilidad de apropiación de cuentas.

Nota: Actualmente, la comprobación de SIM Swap solo es compatible con números de los siguientes países/regiones: Brasil, Indonesia.

Esta API proporciona dos endpoints independientes:

• Retrieve Date: consultar la hora del último SIM Swap ocurrido para un número de teléfono especificado
• Check: detectar si ha ocurrido un SIM Swap para un número de teléfono especificado en las últimas N horas

Verificación de llamada

Ambos endpoints utilizan el método de autenticación HTTP Basic Auth. Añada Authorization en el encabezado HTTP:

              
              Authorization: Basic ${base64_auth_string}

            

El algoritmo de generación para ${base64_auth_string} es: base64(dev_key:dev_secret).

Para obtener más detalles, consulte Verificación de llamada para aprender cómo realizar la autenticación de la API.

Retrieve Date

Consultar la hora del último SIM Swap ocurrido para un número de teléfono especificado.

Dirección de llamada

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

Ejemplo de solicitud

Un objeto de solicitud se expresa en formato JSON, por lo que el encabezado de la solicitud debe incluir Content-Type: application/json.

Encabezado de solicitud

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

            

Cuerpo de solicitud

              
              {
  "phone_number": "+381692223535"
}

            

Parámetros de solicitud

Parámetros de respuesta

Respuesta de éxito

Ejemplo de respuesta de éxito:

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

            

Respuesta de error

El código de estado HTTP es 4xx o 5xx, y el cuerpo de la respuesta contiene los siguientes campos:

Ejemplos comunes de respuestas de error:

Ejemplo de error de parámetro:

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

            

Ejemplo de saldo insuficiente:

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

            

Ejemplo de número fuera del área de cobertura del servicio:

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

            

Ejemplo de fallo general:

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

            

Check

Detectar si ha ocurrido un SIM Swap para un número de teléfono especificado en las últimas N horas.

Dirección de llamada

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

Ejemplo de solicitud

Un objeto de solicitud se expresa en formato JSON, y el encabezado de la solicitud también debe incluir Content-Type: application/json.

Encabezado de solicitud

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

            

Cuerpo de solicitud

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

            

Parámetros de solicitud

Parámetros de respuesta

Respuesta de éxito

Ejemplo de respuesta de éxito:

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

            

Respuesta de error

La estructura es la misma que la del endpoint Retrieve Date. Ejemplo específico de respuesta de error:

Error de parámetro (max_age fuera de rango):

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

            

Códigos de error