Documentación

API de ScanMessage

La API de ScanMessage permite integrar la detección de fraude por mensajes directamente en tu producto: tu backend envía un mensaje sospechoso y recibe un score de riesgo, las señales detectadas y una explicación en lenguaje simple. Esta guía cubre lo necesario para integrarla: autenticación, el endpoint de análisis, los campos de la solicitud y la respuesta, y los errores que puedes recibir.

Autenticación

Todas las solicitudes requieren un token enviado en el header Authorization con el esquema Bearer:

Authorization: Bearer tu_api_key

Cómo obtener tu token

Por ahora la emisión de tokens es manual: escríbenos a hello@scanmessage.dev indicando el nombre de tu empresa y el volumen estimado de solicitudes, y te asignaremos una API key junto con un límite diario de uso.

¿Necesitas ayuda?

Un token ausente, mal formado o inactivo siempre responde 401 — nunca se procesa un mensaje sin autenticación válida.

Endpoint de análisis

URL base

https://api.scanmessage.dev

Endpoint

POST/v1/analyze

Headers requeridos

Authorization: Bearer <tu_api_key>
Content-Type: application/json

Cuerpo de la solicitud

Envía un JSON con el mensaje a analizar:

{
  "message": "Tu cuenta sera bloqueada en 24h, verifica aqui: bit.ly/xyz123",
  "channel": "sms",
  "sender": "+573001234567"
}

messagestring, requerido. Entre 10 y 5000 caracteres. El texto del mensaje sospechoso.

channelstring, requerido. Uno de: "sms", "whatsapp". (La opción "No sé" de la interfaz web es solo para la UI; la API no la acepta.)

senderstring, opcional. Número o identificador del remitente. Se almacena siempre con hash, nunca en texto plano.

Respuesta

Una respuesta exitosa (200) devuelve:

{
  "analysis_id": "b3f1...",
  "cached": false,
  "risk_score": 0.87,
  "risk_level": "high",
  "fraud_type": "phishing",
  "confidence": "high",
  "detected_language": "es",
  "signals_found": [
    { "type": "urgency", "description": "Lenguaje de urgencia extrema." },
    { "type": "suspicious_url", "description": "El enlace no corresponde a un dominio verificado." }
  ],
  "explanation": "Este mensaje combina...",
  "recommendation": "No hagas clic en el enlace...",
  "url_intelligence": []
}

—risk_score — número entre 0.0 y 1.0: probabilidad de fraude.
—risk_level — uno de: minimal, low, moderate, high, critical.
—fraud_type — uno de: phishing, scam, social_engineering, spam, legitimate, unknown.
—confidence — uno de: high, medium, low.
—detected_language — código de idioma ISO 639-1 (ej. "es", "en"), detectado automáticamente a partir del mensaje.
—signals_found — lista de señales detectadas. Cada una trae un type libre (ej. urgency, suspicious_url) y una description en lenguaje simple.
—explanation / recommendation — texto en lenguaje simple: por qué el mensaje es riesgoso y qué hacer al respecto.
—url_intelligence — información adicional sobre enlaces detectados (antigüedad del dominio, estado HTTP). Puede llegar vacía: se completa de forma asíncrona hasta ~15 minutos después.

Respuesta

analysis_id y cached se incluyen para trazabilidad: si el mismo mensaje ya fue analizado recientemente, cached es true y la respuesta es inmediata.

Códigos de error

401Token ausente, mal formado, inválido o inactivo.

422El cuerpo de la solicitud no cumple la validación (mensaje muy corto o largo, canal inválido, etc).

429Límite de solicitudes superado, por IP (ventana de 1 minuto) o por la cuota diaria de tu API key. La respuesta incluye el header Retry-After.

500Error interno inesperado del servicio.

503El motor de análisis no está disponible temporalmente. Reintenta con backoff.

Toda respuesta, exitosa o no, incluye un header X-Request-ID. Inclúyelo si nos escribes para reportar un problema con una solicitud puntual.

Límites de uso

—Por IP: un límite por minuto aplicado a nivel de infraestructura, pensado como protección contra abuso y no como tu cuota contratada.
—Por API key: una cuota diaria asignada a tu token según tu acuerdo con nosotros. Se reinicia cada 24 horas. Si necesitas un límite mayor, escríbenos.

Versionado

Todas las rutas usan el prefijo /v1. Si en el futuro publicamos una v2, la v1 seguirá funcionando durante un período de transición anunciado con anticipación.

Ejemplo completo

curl -X POST https://api.scanmessage.dev/v1/analyze \
  -H "Authorization: Bearer tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Tu cuenta sera bloqueada en 24h, verifica aqui: bit.ly/xyz123",
    "channel": "sms"
  }'

¿Necesitas ayuda?

Escríbenos a hello@scanmessage.dev para solicitar tu API key, aumentar tu límite diario o resolver dudas técnicas de integración.